Skip to navigation

Jobs

Every call creates a job. 200 and 202 return the same object.
View as Markdown

A capability call creates one job. The answer, a stream and a webhook all carry the same Job object.

The Job object

{
"object": "job",
"id": "job_01JC9M…",
"capability": "parse",
"status": "succeeded",
"deadline": "asap",
"created_at": "2026-11-07T14:02:11Z",
"completed_at": "2026-11-07T14:02:13Z",
"output": { "output": { "markdown": "…", "json": { "pages": [] } } },
"error": null,
"usage": { "credits": 2, "units": { "page_parsed": 1 } }
}
FieldTypeMeaning
objectstringAlways job.
idstringjob_ and a ULID.
capabilitystringThe capability of the job, for example parse.
statusstringOne of the statuses.
deadlinestringOnly asap. Another value in the request gives 400 deadline_not_supported.
created_atstringISO 8601 time.
completed_atstring or nullISO 8601 time of the terminal status. Null while the job runs.
outputobject or nullThe output of a succeeded job.
errorobject or null{code, message, retryable, details?} of a job that did not succeed.
usageobject or null{credits, units}: the metered use. Null while the job runs.
run_idstringThe Run run id. Agent jobs only.
required_actionobject or nullWhat a needs_input job waits for. Machine jobs only. Read Machines.

Statuses

StatusTerminalMeaning
queuedNoThe API accepted the job. The work has not started.
runningNoThe work runs.
needs_inputNoThe job waits for a person, for example a signature. It holds no concurrency slot.
succeededYesoutput holds the result.
failedYeserror holds the reason. The job costs nothing.
cancelledYesThe creating credential cancelled the job.
expiredYesThe work passed its time limit. The job costs nothing.

A job in a terminal status never changes. The first terminal result wins.

A failed job answers 200 with status: "failed". There is one exception: when the capability does not answer, the answer is 503 capability_unavailable. A validation error (400) creates no job.

Read the output

The shape of output depends on the capability. The paperwork capabilities have the result in output.output. An agent job has the result of the run in output.result.

A parse has two output forms, because a job can run on two paths:

PathWhenOutput fields
InlineA small PDF or image from a URL, with a wait of 5 seconds or more.output.output.markdown and output.output.json (with pages), in the answer.
DurableEvery other parse, for example Prefer: respond-async or a large file.output.output.markdownUrl and output.output.jsonUrl, signed URLs to the files.

Read both forms in your client. The same request can use either path. The inline path reads a source of at most 50 MB: 10 pages with no OCR, or 3 pages with OCR.

A signed URL expires after about 1 hour. GET /v2/jobs/{id} returns new URLs for a job older than 45 minutes, for up to 7 days. GET /v2/jobs returns the stored URLs.

Classify and split answers on the inline path have their fields in output.output, for example output.output.documents and output.output.splits. They do not include the fields that name stored files.

The stored output is at most 1 MiB. A larger output fails the job with output_too_large.

Job error codes

error.code of a job that did not succeed is one of these values:

CodeMeaningretryable
invalid_requestThe capability refused the input during the job.No
output_too_largeThe output is larger than 1 MiB.No
rate_limitedA downstream service limited the job.Yes
credits_exhaustedThe plan or the credit balance stops the job. error.details.cause can give the reason.No
capability_unavailableThe capability did not answer.Yes
capability_lostThe capability stopped before it finished.Yes
agent_protection_unsupportedThe agent uses Cloudflare Access protection, which API v2 does not bypass.No
processing_failedThe work failed. error.details.cause holds the original code.Depends
cancelledThe creating credential cancelled the job.No
expiredThe work passed its time limit.No

Use the retryable field of the error. The table shows the usual value.

Read a job

curl -s "https://$CRK_SLUG.cloudraker.run/v2/jobs/job_01JC9M…" \
-H "Authorization: Bearer $CRK_API_KEY"

Send Prefer: wait=N to hold the request until the job ends, the job needs input, or the wait ends. The answer is always 200 with the job. Read Sync and async.

List jobs

GET /v2/jobs lists the jobs of the environment of the credential, newest first. It needs the scope jobs:read.

Query parameterMeaning
capabilityFilter by capability.
statusFilter by status.
created_afterISO 8601 time. Jobs created at or after it.
created_beforeISO 8601 time. Jobs created before it.
limit1 to 100. The default is 20.
cursorThe next_cursor of the page before.
{ "object": "list", "data": [], "next_cursor": null }

Access to a job

CredentialRead and streamListCancel
The credential that created the jobYesNeeds jobs:readYes
Another credential with jobs:read, in the same environmentYesYesNo
Another credential without jobs:readNoNoNo
A credential of the other environmentNoNoNo

The creating credential can read its own jobs with no extra scope. jobs:read lists the jobs of the environment of the credential. It also reads the jobs of other credentials in the same environment.

Test jobs and live jobs are separate. A credential of the other environment gets 404 job_not_found, also with jobs:read.

Without access, a read gets 404 job_not_found. So the answer does not show that the job exists. For a crt_ token or a JWT, the credential is the trust.

Cancel a job

curl -s -X POST "https://$CRK_SLUG.cloudraker.run/v2/jobs/job_01JC9M…/cancel" \
-H "Authorization: Bearer $CRK_API_KEY"

The answer is 200 with the job in the cancelled status. Only the creating credential can cancel a job. Another credential gets 404 job_not_found, also with jobs:read. A job that ended gets 409 job_not_cancellable. If the capability cannot stop the work now, the answer is 503 capability_unavailable and the job does not change.

Retention

The API keeps a job for 30 days. A later read gets 404 job_not_found.