Check a job

The poll half of start-then-poll. Any key on the account can read it, including a read-only one - checking on work costs nothing and spends nothing.

GET/v1/jobs/{job_id}

Parameters

Param	In	Notes
job_id	path	The id the article or batch call returned. Another account's job is a 404, and so is a segment that is not a UUID.

Request

curl https://api.mastheads.app/v1/jobs/7c2b9f10-4a5d-4e88-9b31-6f0c2a1d5e73 \
  -H "Authorization: Bearer mh_live_your_key_here"

Response

200 OK

{
  "id": "7c2b9f10-4a5d-4e88-9b31-6f0c2a1d5e73",
  "status": "done",
  "domain_id": "3f9c1e84-2b7a-4d6e-9c15-8a0d7e6b4f21",
  "created_at": "2026-07-05T08:12:00+00:00",
  "error": null,
  "article_id": "a1d4c7b2-5e83-4f19-b06c-2d9f8e3a7c54"
}

Poll on a timer rather than in a loop: the 120 requests a minute this key gets are shared with everything else it reads.

Field	Type	Notes
status	string	queued, running, done or failed.
domain_id	string	The domain the job was started on.
error	string	Why it failed, in a sentence. null while the job is alive and when it succeeded.
article_id	string	Present only once status is done, and null if the job finished without producing an article. Read it with GET /v1/editions/{slug}/articles/{article_id}.

Errors

Status	Code	When
401	invalid_key	Missing, invalid, or revoked API key.
401	account_closed	The account this key belongs to has been closed.
402	plan_required	The account's current plan does not include the content API. This is checked on the request, not only when the key was made.
404	not_found	No such job on your account, or the id is not a UUID. Another account's job is a 404, never a 403.
429	rate_limited	Over 120 requests/minute on this key. Retry-After: 60.
503	unavailable	The plan or the data store could not be read. It refuses rather than guessing.

Every request needs a key - Authentication. The error shape and the full status table are on Rate limits & errors.