---
title: "List document jobs"
method: GET
path: "/v1/documents/jobs"
tags: ["Documents"]
---

# List document jobs

`GET /v1/documents/jobs`

## Request

- Base URL: `https://console.nace.ai`
- URL: `https://console.nace.ai/v1/documents/jobs`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/drex-api/docs/v1/documents/jobs/get.ts> (a function with typed inputs; its response is checked against the schema)

The account's own jobs, newest first by when Drex received each request. `created_at` is when the job started, so jobs sent within a moment of each other can list a little out of `created_at` order. Readable at any balance. A job you deleted is not listed.

## Query parameters

- `limit` integer
- `cursor` string
- `operation` 'parse' | 'split' | 'classify' | 'extract' | 'ground'
- `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled'

## Response `200`

One page of jobs.

- DocumentJobList
  - `items` DocumentJob[], required: The account's jobs, newest first, without `result`.
    - `job_id` string, uuid, required
    - `kind` 'parse' | 'split' | 'classify' | 'extract' | 'ground', required
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
    - `result` unknown
    - `credits` integer, nullable: Credits the job used; final once `usage_final` is true. Drex charges the job's final billable usage once, at the USD price pinned when it was admitted (see Models & pricing). `credits` is the document service's usage count, not a multiplier for the per-page or per-target price. A failed job is never charged, including when it produced partial results. A job cancelled before completion is not charged, including delivered parts.
    - `usage_final` boolean
    - `timing` DocumentTiming: Original server-side Parse service timing, in milliseconds. Total includes preparation, NDI queueing/processing and active final result preparation. Upload, browser network/rendering and idle time awaiting another client read are excluded. The first usable published preview and final result use the same origin. Missing measurements remain null. Historical jobs can omit timing.
      - `received_at` string, date-time, required: When the original Parse handler received its request, before authentication and admission. Replays preserve this origin.
      - `observed_at` string, date-time, required: Server time of this timing snapshot.
      - `completed_at` string, date-time, nullable, required: First time the service prepared the terminal response, preserved across subsequent reads.
      - `elapsed_ms` integer, nullable, required: Current server elapsed estimate, or frozen total_ms once completed.
      - `total_ms` integer, nullable, required: Frozen service duration: preparation_ms + queue_ms + ndi_processing_ms + result_preparation_ms. Null until completed. delivery_wait_ms is excluded.
      - `first_response_ms` integer, nullable, required: Original request to first usable preview publication on the server. For atomic delivery, equals total_ms. Null if not measured; browser rendering and transport are excluded.
      - `breakdown` DocumentTimingBreakdown, required
        - `preparation_ms` integer, nullable, required: Original Drex request receipt to NDI job creation, including authentication, admission, source checks and internal submission.
        - `queue_ms` integer, nullable, required: NDI job creation to its processing start.
        - `ndi_processing_ms` integer, nullable, required: NDI processing start to finish, including document finalization.
        - `result_preparation_ms` integer, nullable, required: Active result-read request work after NDI finishes, including internal transfer, funding settlement and result preparation.
        - `delivery_wait_ms` integer, nullable, required: Idle interval after NDI finishes and before the request that prepares the final result begins. Excluded from total_ms; reopening a completed job does not inflate processing time.
        - `document_finalization_ms` integer, nullable, required: All requested previews being saved to NDI finishing; included inside ndi_processing_ms, not an additional summand. Null if publication milestones were not measured.
    - `cost` DocumentCost
      - `currency` 'USD', required
      - `pricing_version` string, required
      - `total_usd` string, required: Exact decimal USD wallet charge.
      - `lines` DocumentCostLine[], required
        - `operation` 'parse' | 'split' | 'classify' | 'extract' | 'ground', required
        - `quantity` integer, required
        - `unit` 'page' | 'target', required
        - `execution` 'fresh' | 'reused', required
        - `unit_price_usd` string, required
        - `amount_usd` string, required
        - `reuse_reason` string, nullable, required
  - `next_cursor` string, nullable, required: Pass as `cursor` for the next page; null on the last page.

## Other responses

- `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`).
- `422`: A query parameter is invalid (`invalid_request_error`).
- `429`: Over the account's requests per minute for document routes, or the document service is throttling this account (`rate_limit_error`).
- `500`: Something failed on Drex's side (`internal_error`).
- `502`: The document service refused Drex's own request (`upstream_error`, code `ndi_refused_drex`). Retry later.
- `503`: The document service is unavailable (`service_unavailable`).
- `504`: The document service timed out (`upstream_error`).
- `529`: The public API is paused (code `service_disabled`) (`overloaded`).

---

[API](https://skmtc.dev/nace/apis/drex-api.md) - [All operations](https://skmtc.dev/nace/apis/drex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/drex-api/revisions/a0e62d925a61?raw)