Get Job

Poll GET /v1/jobs/:id for extraction job status, fill-rate progress, current pipeline phase, document counts, and grid statistics until the job completes.

GET /v1/jobs/:id returns the current status and progress of an extraction job: the lifecycle status (pending, queued, processing, complete, failed), a fill-rate progress percentage, per-document completion counts, and cell-level grid statistics. It is the polling target after POST /v1/jobs: call it every few seconds until status reaches complete, then fetch the results endpoint.

GET/v1/jobs/:id

Request

Response

Response fields

idstringJob UUID.

namestring | nullOptional human-readable job name.

statusstringJob status: pending, queued, processing, complete, failed.

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

estimated_seconds_remaininginteger | nullEstimated seconds until completion. Currently always null.

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

document_countintegerTotal number of documents in the job.

completed_documentsintegerNumber of documents fully processed.

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

current_phasestring | nullCurrent pipeline phase (e.g. phase_2_execute).

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

created_atstringISO 8601 creation timestamp.

started_atstring | nullISO 8601 start timestamp.

completed_atstring | nullISO 8601 completion timestamp.

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

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Q4 Invoice Run",
  "status": "processing",
  "progress": 65,
  "estimated_seconds_remaining": null,
  "schema": { "id": "sch_uuid_1", "name": "Invoice" },
  "document_count": 48,
  "completed_documents": 31,
  "grid_stats": {
    "total_cells": 2016,
    "filled": 1310,
    "empty": 706,
    "fill_rate": 0.65
  },
  "current_phase": "phase_2_execute",
  "created_at": "2024-09-14T10:32:00.000Z",
  "started_at": "2024-09-14T10:32:05.000Z",
  "completed_at": null,
  "links": {
    "self": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cancel": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel",
    "dashboard": "https://app.talonic.com/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Watch current_phase to track pipeline progression: it moves through values such as phase_1_resolve, phase_2_strategy, phase_2_execute, phase_2_outliers, phase_3_validation, and phase_4_reread before landing on completed (or error). The grid_stats.fill_rate value increases as each phase completes, giving you a real-time quality signal before the job reaches complete status.

The progress value is fill-rate based: it is the percentage of grid cells filled so far, not elapsed time. It is only present while the job is processing and returns to null once the job is terminal.

Errors

Error responses

400validation_errorInvalid job ID format. Must be a UUID.

401unauthorizedMissing or invalid API key.

404not_foundNo job with this ID exists for your organization.

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