Skip to main content
POST
Cancel job

What it costs

The key needs jobs:cancel. The call is free. It takes no body; a body sent is refused 400 invalid-request.

Refused before any work

An id of the wrong kind: 400 invalid-request, before any lookup. A body sent: 400 invalid-request. An unknown query parameter: 400 invalid-request, unknown_field.

Problem types

  • 400 invalid-request, The request is invalid.
  • 401 unauthorized, The key is missing or rejected.
  • 403 insufficient-scope, The key lacks a scope this call needs.
  • 404 not-found, Not found: an unknown or another account’s job.
  • 410 job-expired, The job has expired: the job ended more than 30 days ago; the answer comes for 30 more days, to the owning account only, then 404.
  • 429 rate-limit-exceeded, The rate limit is exceeded; concurrency-limit-exceeded, Too many calls are in flight.
  • 500 internal-error, The service failed.
  • 503 overloaded, The service is overloaded.

Authorizations

Authorization
string
header
required

An API key from https://app.getclean.ai, or an access token issued by https://auth.getclean.ai/realms/getclean, sent as Authorization: Bearer <key> on every call. The scopes a key carries and what a 401 and a 403 say are on the keys and sign-in page.

Headers

traceparent
string

Your own trace id for the call, the W3C Trace Context traceparent header, optional on every operation. getclean logs it with the call, so a request in your traces can be matched to its Request-Id, and never forwards it to a site or a source, a stated departure from W3C Trace Context section 3.4, which asks a vendor to pass it on. A malformed value is ignored, never refused, as the same recommendation asks.

Path Parameters

job_id
string
required

The job to stop, a job_ id.

Pattern: ^job_[A-Za-z0-9]{22}$

Response

The job in its current state after the ask; Retry-After and retry_after_seconds while it still runs; once canceled, its outcome and contents_id when pages were done.

A parse that outlives its request. completed when its record is delivered or partial, failed otherwise, with problem set when nothing was made; canceled keeps and bills the pages done. Kept 30 days after its end, then 410 job-expired for 30 days, then 404. A job carries no notices and no version.

id
string
required

The job's id, job_ and 22 random characters; another account's id answers 404.

Pattern: ^job_[A-Za-z0-9]{22}$
Example:

"job_8Rt2mqXKclxu58MCwLkSCV"

kind
string
required

The operation that started the job, upload_contents; an open set.

Example:

"upload_contents"

state
string
required

The job's state: queued, running, completed, failed or canceled; the last three are final. An open set.

Examples:

"queued"

"running"

"completed"

"failed"

"canceled"

finished
boolean
required

True once the state is final.

counts
object
required

The pages parsed, failed and remaining, adding up to pages.count; zeros while the job is queued or the count unread.

cost
object
required

The units so far on every read, the final figure once finished; zero on a cancel with no page done.

created_at
string<date-time>
required

When the job started, RFC 3339 in UTC.

Example:

"2026-11-04T10:02:11Z"

updated_at
string<date-time>
required

When the job last changed, RFC 3339 in UTC.

Example:

"2026-11-04T10:14:52Z"

request_id
string
required

The id of the call this copy of the job came back in, the same as that call's Request-Id header.

Pattern: ^req_[A-Za-z0-9]{22}$
Example:

"req_01Qm89u0cStrgTL7bxmqKa"

stage
string

What the job is doing now, parsing or recognizing; an open set. Absent on queued and when final.

Examples:

"parsing"

"recognizing"

outcome
object

The record's outcome. Present once a record exists.

retry_after_seconds
integer

Seconds to wait before reading again, equal to the Retry-After header of get_job and cancel_job; inside a JobPage, each job's own wait. Absent once final.

Required range: x >= 1
contents_id
string

The record the job made, read by get_contents. Present once a record exists.

Pattern: ^cnt_[A-Za-z0-9]{22}$
Example:

"cnt_f9a1LknFzePvIKv1pEkejs"

problem
object

Why the job failed before a record existed, without status, its request_id and instance the upload's. Present only on a job that failed with no record.

expires_at
string<date-time>

When the job expires, 30 days after it ended, RFC 3339 in UTC. Absent until final.

Example:

"2026-12-04T10:14:52Z"