> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Jobs

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

## The Job object

```json
{
  "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 } }
}
```

| Field             | Type           | Meaning                                                                                                             |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `object`          | string         | Always `job`.                                                                                                       |
| `id`              | string         | `job_` and a ULID.                                                                                                  |
| `capability`      | string         | The capability of the job, for example `parse`.                                                                     |
| `status`          | string         | One of the [statuses](#statuses).                                                                                   |
| `deadline`        | string         | Only `asap`. Another value in the request gives `400 deadline_not_supported`.                                       |
| `created_at`      | string         | ISO 8601 time.                                                                                                      |
| `completed_at`    | string or null | ISO 8601 time of the terminal status. Null while the job runs.                                                      |
| `output`          | object or null | The output of a succeeded job.                                                                                      |
| `error`           | object or null | `{code, message, retryable, details?}` of a job that did not succeed.                                               |
| `usage`           | object or null | `{credits, units}`: the metered use. Null while the job runs.                                                       |
| `run_id`          | string         | The Run run id. Agent jobs only.                                                                                    |
| `required_action` | object or null | What a `needs_input` job waits for. Machine jobs only. Read [Machines](/paperwork/v2/machines#the-required-action). |

## Statuses

| Status        | Terminal | Meaning                                                                            |
| ------------- | -------- | ---------------------------------------------------------------------------------- |
| `queued`      | No       | The API accepted the job. The work has not started.                                |
| `running`     | No       | The work runs.                                                                     |
| `needs_input` | No       | The job waits for a person, for example a signature. It holds no concurrency slot. |
| `succeeded`   | Yes      | `output` holds the result.                                                         |
| `failed`      | Yes      | `error` holds the reason. The job costs nothing.                                   |
| `cancelled`   | Yes      | The creating credential cancelled the job.                                         |
| `expired`     | Yes      | The 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`](/paperwork/v2/errors#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:

| Path    | When                                                                    | Output fields                                                                      |
| ------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Inline  | A 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.   |
| Durable | Every 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:

| Code                           | Meaning                                                                                  | `retryable` |
| ------------------------------ | ---------------------------------------------------------------------------------------- | ----------- |
| `invalid_request`              | The capability refused the input during the job.                                         | No          |
| `output_too_large`             | The output is larger than 1 MiB.                                                         | No          |
| `rate_limited`                 | A downstream service limited the job.                                                    | Yes         |
| `credits_exhausted`            | The plan or the credit balance stops the job. `error.details.cause` can give the reason. | No          |
| `capability_unavailable`       | The capability did not answer.                                                           | Yes         |
| `capability_lost`              | The capability stopped before it finished.                                               | Yes         |
| `agent_protection_unsupported` | The agent uses Cloudflare Access protection, which API v2 does not bypass.               | No          |
| `processing_failed`            | The work failed. `error.details.cause` holds the original code.                          | Depends     |
| `cancelled`                    | The creating credential cancelled the job.                                               | No          |
| `expired`                      | The work passed its time limit.                                                          | No          |

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

## Read a job

```bash
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](/paperwork/v2/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 parameter  | Meaning                                     |
| ---------------- | ------------------------------------------- |
| `capability`     | Filter by capability.                       |
| `status`         | Filter by status.                           |
| `created_after`  | ISO 8601 time. Jobs created at or after it. |
| `created_before` | ISO 8601 time. Jobs created before it.      |
| `limit`          | 1 to 100. The default is 20.                |
| `cursor`         | The `next_cursor` of the page before.       |

```json
{ "object": "list", "data": [], "next_cursor": null }
```

## Access to a job

| Credential                                                   | Read and stream | List              | Cancel |
| ------------------------------------------------------------ | --------------- | ----------------- | ------ |
| The credential that created the job                          | Yes             | Needs `jobs:read` | Yes    |
| Another credential with `jobs:read`, in the same environment | Yes             | Yes               | No     |
| Another credential without `jobs:read`                       | No              | No                | No     |
| A credential of the other environment                        | No              | No                | No     |

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

```bash
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`.