Run Detail

Get the status, progress, and summary of a matching run, plus its top results with per-field evidence. Status moves from queued through running to completed.

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 results by confidence. Each result includes document_id, matched_reference_row_id, confidence score, a match status (matched, review, or no_match), and an evidence object with the per-field contributions behind the score.

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 reclassify individual results after human inspection. 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, error, cancelled, or ai_resolving.

triggered_bystringHow the run was triggered.

rows_processedinteger | nullRows evaluated so far.

rows_matchedinteger | nullRows whose result status is matched (confidence at or above the threshold).

avg_confidencenumber | nullAverage confidence across all results.

started_atstring | nullISO 8601 start timestamp.

completed_atstring | nullISO 8601 completion timestamp.

errorstring | nullError message if status is error.

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[].statusstringMatch status: matched (confidence ≥ threshold), review (between 0.4 and the threshold), or no_match.

results[].evidenceobject | nullEvidence breakdown: field_contributions[], candidates_considered, top_n_candidates[], and blocking_method. Null when no candidate scored.

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": "matched",
      "evidence": {
        "field_contributions": [
          { "extracted_field": "vendor_name", "extracted_value": "Acme Corp GmbH", "reference_value": "Acme Corp", "match_type": "fuzzy_string", "matched": true, "weight": 0.4, "score": 0.95, "contribution": 0.38 },
          { "extracted_field": "invoice_date", "extracted_value": "2024-09-28", "reference_value": "2024-09-30", "match_type": "date_range", "matched": true, "weight": 0.3, "score": 1.0, "contribution": 0.3 },
          { "extracted_field": "amount", "extracted_value": 14250.00, "reference_value": 14250.50, "match_type": "numeric_range", "matched": true, "weight": 0.3, "score": 0.82, "contribution": 0.25 }
        ],
        "candidates_considered": 3,
        "top_n_candidates": [
          { "reference_row_id": "ref_row_42", "confidence": 0.92 },
          { "reference_row_id": "ref_row_87", "confidence": 0.61 }
        ],
        "blocking_method": null
      }
    }
  ]
}

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.

Frequently asked questions

Why does the run detail only show 50 results?+

The run detail endpoint includes the top 50 results by confidence for quick inspection. Use GET /v1/matching/runs/:id/results with pagination for the full result set.

What does the ai_resolving status mean?+

The run has completed standard field-level matching and is now running an AI resolution pass (using Claude Haiku) on rows with low confidence scores. This can upgrade borderline matches or confirm non-matches.

How often should I poll the matching run detail endpoint?+

A typical pattern is to check every 5 to 10 seconds while status is queued or running. For lighter-weight progress updates during long runs, use GET /v1/matching/runs/:id/progress instead.

Run Detail

Response

Errors

Frequently asked questions

Related