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.

Retrieve the current state of a matching run. Poll this endpoint while status is queued or running to track progress. Once completed, the response includes the top 50 results by confidence. Use the results endpoint for full paginated access.

Poll this endpoint after triggering a run via POST /v1/matching/configs/:id/run. A typical polling pattern is to check every 5-10 seconds while status is queued or running. Use GET /v1/matching/runs/:id/progress for lighter-weight progress updates during long runs.

Once completed, the response includes rows_processed, rows_matched, and avg_confidence at the run level, plus a results array with the top 50 matches by confidence. Each result includes document_id, matched_reference_row_id, confidence score, review status (pending, approved, rejected), and per-field evidence breakdown.

For the full result set beyond the top 50, use GET /v1/matching/runs/:id/results with pagination. Use POST /v1/matching/runs/:runId/results/:resultId/review to approve or reject individual matches. If status is ai_resolving, the run is using Claude Haiku to disambiguate borderline matches — this phase adds latency but can significantly improve accuracy on ambiguous rows.

The ai_resolving status indicates that the run has finished standard matching and is now running an AI resolution pass on low-confidence rows. This pass uses Claude Haiku to disambiguate borderline matches.
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