List Jobs

List document extraction jobs with status, progress, and cursor pagination. Filter by pending, queued, processing, complete, or failed status via the API.

Jobs (formerly called structuring runs) are Talonic's quick ad-hoc runs for asynchronous document extraction: GET /v1/jobs lists every job in your organization with its status, progress, and grid statistics. You create a job with a schema and a set of documents, poll it until it completes, then read the structured rows from the results endpoint. Each job runs the standard 4-phase extraction pipeline.

The 4-phase pipeline consists of: Phase 1 (Resolve) which fills 60-80% of cells using registry transfer, raw extraction mapping, lookup cascades, and deterministic compute; Phase 2 (Planner) in which the Planner uses Claude to extract remaining values; Phase 3 (Resolve II) which normalizes LLM-extracted values to canonical codes; and Phase 4 (Transform) which applies deterministic transforms, validation, and format constraints.

Jobs are the ad-hoc tier: one call against a schema, no Spec required. If you have curated a Spec — a schema plus its rail, resolution policies, and validation gates — run it through POST /v1/pipelines instead; the pipelines API compiles the Spec's rail server-side and enforces review holdback.

GET/v1/jobs

Query parameters

statusstringFilter by status: pending, queued, processing, complete, failed.

limitintegerMaximum number of results to return. Default: 20

cursorstringPagination cursor from a previous response.

orderstringSort direction by created_at. Default: desc

afterstringReturn jobs created after this ISO 8601 timestamp.

beforestringReturn jobs created before this ISO 8601 timestamp.

Request

Response

Response fields

dataarrayArray of job objects.

data[].idstringJob UUID.

data[].namestring | nullOptional human-readable job name.

data[].statusstringJob status: pending, queued, processing, complete, failed.

data[].progressinteger | nullFill-rate progress percentage (0–100). Only set while status is processing.

data[].estimated_seconds_remaininginteger | nullEstimated seconds until completion. Currently always null.

data[].schemaobject | nullSchema used for this job: { id, name }.

data[].document_countintegerTotal number of documents in the job.

data[].completed_documentsintegerNumber of documents fully processed.

data[].grid_statsobject | nullCell-level stats: { total_cells, filled, empty, fill_rate }.

data[].current_phasestring | nullCurrent pipeline phase (e.g. phase_2_execute).

data[].errorobject | nullError details when status is failed: { code, message }.

data[].created_atstringISO 8601 creation timestamp.

data[].started_atstring | nullISO 8601 start timestamp.

data[].completed_atstring | nullISO 8601 completion timestamp.

data[].linksobjectRelated resource URLs (self, cancel if active, dashboard).

pagination.totalintegerTotal number of jobs matching the query.

pagination.limitintegerMaximum results per page.

pagination.has_morebooleanWhether more results exist beyond this page.

pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Q4 Invoice Run",
      "status": "complete",
      "progress": null,
      "estimated_seconds_remaining": null,
      "schema": { "id": "sch_uuid_1", "name": "Invoice" },
      "document_count": 48,
      "completed_documents": 48,
      "grid_stats": {
        "total_cells": 2016,
        "filled": 1890,
        "empty": 126,
        "fill_rate": 0.94
      },
      "current_phase": null,
      "created_at": "2024-09-14T10:32:00.000Z",
      "started_at": "2024-09-14T10:32:05.000Z",
      "completed_at": "2024-09-14T10:35:22.000Z",
      "links": {
        "self": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "dashboard": "https://app.talonic.com/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ],
  "pagination": {
    "total": 67,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTA5LTE0VDEwOjMyOjAwLjAwMFoiLCJpZCI6ImExYjJjM2Q0In0="
  }
}

The links.cancel URL is only present while a job is pending or processing. Its absence tells you the job is already terminal without inspecting the status field.

Errors

Error responses

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Create Job

Get Job

Job Results

Run Pipeline (governed Spec runs)