Skip to main content

Job Results

Retrieve structured extraction results for a job: one JSON row per document with field values keyed by schema field, a confidence score, and validation flags.

GET /v1/jobs/:id/results returns the structured extraction results of a job as JSON: one row per document, with the extracted field values keyed by your schema's field names, a row-level confidence score, and any validation flags raised during Phase 4. Results are available progressively as each pipeline phase flushes to the database, so you can read partial output before the job completes.

Results are available even while the job is still processing. The grid flushes to the database after each phase, so you can read partial results before the job completes.
GET/v1/jobs/:id/results

Request

curl https://api.talonic.com/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/results \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

job_idstringJob UUID.
job_statusstringCurrent job status (complete, processing, failed, etc.).
schemaobject | nullSchema used for this job: { id, name }.
total_rowsintegerTotal number of result rows.
dataarrayArray of result row objects.
data[].idstringResult row UUID.
data[].document_idstringSource document UUID.
data[].filenamestringSource document filename.
data[].statusstringRow processing status: pending, processing, completed, or failed.
data[].valuesobjectExtracted field values keyed by field name.
data[].confidencenumber | nullRow-level confidence score (0–1), averaged across all field confidences.
data[].validation_flagsarrayValidation flag objects for this row: { field, type, message, severity }.
links.selfstringURL of this results resource.
links.jobstringURL of the parent job.

Response

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_status": "complete",
  "schema": { "id": "sch_uuid_1", "name": "Invoice" },
  "total_rows": 2,
  "data": [
    {
      "id": "res_uuid_1",
      "document_id": "doc_uuid_1",
      "filename": "invoice_oct.pdf",
      "status": "completed",
      "values": {
        "invoice_number": "INV-2024-001",
        "vendor": "Acme Corp",
        "total": 4250.00,
        "date": "2024-10-01"
      },
      "confidence": 0.94,
      "validation_flags": []
    },
    {
      "id": "res_uuid_2",
      "document_id": "doc_uuid_2",
      "filename": "invoice_nov.pdf",
      "status": "completed",
      "values": {
        "invoice_number": "INV-2024-002",
        "vendor": "Acme Corp",
        "total": null,
        "date": "2024-11-15"
      },
      "confidence": 0.71,
      "validation_flags": [
        {
          "field": "total",
          "type": "missing_required",
          "message": "Required field has no value after all phases",
          "severity": "error"
        }
      ]
    }
  ],
  "links": {
    "self": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/results",
    "job": "/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Each validation flag is an object with field, type, message, and severity (error or warning). Flag types include missing_required, date_sanity, amount_mismatch, lookup_failed, low_confidence_outlier, and implausible_value. Flags are informational: they never block output, they mark data quality issues detected by Phase 4 cross-field validation. Use them together with the confidence score to prioritize which rows need manual review; values below 0.8 typically warrant inspection.

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.

Frequently asked questions

What do validation_flags contain?+
Each flag is an object with field, type, message, and severity describing a data quality issue found during Phase 4 cross-field validation. Flag types include missing_required, date_sanity, amount_mismatch, lookup_failed, low_confidence_outlier, and implausible_value. An empty array means all checks passed.
Do validation flags block or remove values from the results?+
No. Flags are informational and never block output; the extracted value stays in values even when flagged. Treat severity: "error" flags (such as missing_required) as review candidates and severity: "warning" flags as softer signals.
Can I get results for a failed job?+
Yes. If the job processed some documents before failing, those partial results are available. Check job_status in the response to understand the context.
Can I read results while the job is still running?+
Yes. The grid flushes to the database after each pipeline phase, so this endpoint returns whatever rows exist so far. Poll GET /v1/jobs/:id and re-fetch results until the job reaches complete for the final data.

Related

Get Job
Create Job
List Jobs