Skip to main content

Run Detail

Get the status, progress, and summary of a matching run. Status progresses from queued to running to completed or failed.

GET/v1/matching/runs/:id

Response

Response fields

idstringRun UUID.
matching_config_idstringConfig that triggered this run.
statusstringRun status: queued, running, completed, failed, cancelled, or ai_resolving.
triggered_bystringHow the run was triggered.
rows_processedinteger | nullRows evaluated so far.
rows_matchedinteger | nullRows that produced a match above threshold.
avg_confidencenumber | nullAverage confidence across all matches.
started_atstring | nullISO 8601 start timestamp.
completed_atstring | nullISO 8601 completion timestamp.
errorstring | nullError message if status is failed.
created_atstringISO 8601 creation timestamp.
links.selfstringURL to this run.
links.configstringURL to the config.
resultsarrayTop 50 match results ordered by confidence descending.
results[].idstringResult UUID.
results[].document_idstringSource document UUID.
results[].document_filenamestring | nullSource document filename.
results[].matched_reference_row_idstring | nullMatched reference row ID.
results[].confidencenumberWeighted confidence score (0–1).
results[].statusstringReview status: pending, approved, or rejected.
results[].evidenceobject | nullPer-field evidence breakdown.

Response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "matching_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "triggered_by": "manual",
  "rows_processed": 200,
  "rows_matched": 183,
  "avg_confidence": 0.91,
  "started_at": "2024-10-02T14:00:05.000Z",
  "completed_at": "2024-10-02T14:02:30.000Z",
  "error": null,
  "created_at": "2024-10-02T14:00:00.000Z",
  "links": {
    "self": "/v1/matching/runs/c3d4e5f6-a7b8-9012-cdef-123456789012",
    "config": "/v1/matching/configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "results": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "document_id": "doc_uuid_1",
      "document_filename": "invoice-acme-2024-001.pdf",
      "matched_reference_row_id": "ref_row_42",
      "confidence": 0.92,
      "status": "pending",
      "evidence": {
        "vendor_name": { "strategy": "fuzzy", "score": 0.95 },
        "invoice_date": { "strategy": "date_range", "score": 1.0 },
        "amount": { "strategy": "numeric_range", "score": 0.82 }
      }
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundNo matching run with this ID exists for your workspace.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Results
Run Matching