Skip to main content

List Runs

List matching runs with optional config filtering, cancel in-progress runs, poll lightweight progress updates, and trigger AI resolution on borderline matches.

List all matching runs in the current workspace, optionally filtered by configuration. Each run object includes status, row counts, average confidence, and timing information. Use this endpoint to monitor active runs, review historical executions, or find runs to cancel.

Runs progress through a well-defined lifecycle: queued (waiting for worker), running (actively comparing rows), completed (all rows processed), failed (unrecoverable error), cancelled (user-initiated cancellation), or ai_resolving (AI disambiguation pass on borderline matches). The triggered_by field indicates whether the run was started manually, by schedule, or via the API.

For active runs, use the progress sub-endpoint to get lightweight status updates without loading the full run object. This is ideal for polling UIs — the response includes the current phase, phase-level progress percentage, and running row counts. For runs with a strategy, the ai-resolve endpoint triggers a post-hoc AI resolution pass on the review band to disambiguate borderline matches.

Cancelling a run is only possible while the run is in queued or running status. Once a run reaches completed, failed, or cancelled, the cancel endpoint returns a 409 conflict. Cancelled runs retain any partial results produced before cancellation — use the results endpoint to access them.

Use config_id to filter runs for a specific matching configuration. Without it, all runs across all configs in the workspace are returned.
GET/v1/matching/runs

Response

Response fields

dataarrayArray of matching run objects.
data[].idstringRun UUID.
data[].matching_config_idstringConfig that triggered this run.
data[].statusstringRun status: queued, running, completed, failed, cancelled, or ai_resolving.
data[].triggered_bystringHow the run was triggered (manual, scheduled, api).
data[].rows_processedinteger | nullNumber of rows processed so far.
data[].rows_matchedinteger | nullNumber of rows that produced a match above threshold.
data[].avg_confidencenumber | nullAverage confidence across matched rows.
data[].started_atstring | nullISO 8601 timestamp when the run began processing.
data[].completed_atstring | nullISO 8601 timestamp when the run finished.
data[].errorstring | nullError message if the run failed.
data[].created_atstringISO 8601 creation timestamp.
data[].links.selfstringURL to this run.
data[].links.configstringURL to the config that owns this run.
pagination.totalintegerTotal number of runs.
pagination.limitintegerMaximum results per page.
pagination.has_morebooleanWhether more results exist beyond this page.
pagination.next_cursorstring | nullCursor to fetch the next page.

Response

{
  "data": [
    {
      "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"
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}
POST/v1/matching/runs/:id/cancel

Response (Cancel)

Response fields

idstringRun UUID.
matching_config_idstringConfig that triggered this run.
statusstringUpdated status: cancelled.
triggered_bystringHow the run was triggered.
rows_processedinteger | nullRows processed before cancellation.
rows_matchedinteger | nullRows matched before cancellation.
avg_confidencenumber | nullAverage confidence of matches produced before cancellation.
started_atstring | nullISO 8601 start timestamp.
completed_atstring | nullISO 8601 cancellation timestamp.
errorstring | nullNull for cancelled runs.
created_atstringISO 8601 creation timestamp.
links.selfstringURL to this run.
links.configstringURL to the config that owns this run.

Response (POST /cancel)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "matching_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "cancelled",
  "triggered_by": "manual",
  "rows_processed": 120,
  "rows_matched": 98,
  "avg_confidence": 0.89,
  "started_at": "2024-10-02T14:00:05.000Z",
  "completed_at": "2024-10-02T14:01:15.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"
  }
}
GET/v1/matching/runs/:id/progress

Response (Progress)

Response fields

idstringRun UUID.
statusstringCurrent run status.
phasestringCurrent processing phase (e.g. blocking, scoring, ranking).
phase_progressnumberProgress within the current phase as a percentage (0–100).
rows_processedinteger | nullTotal rows processed so far.
rows_matchedinteger | nullTotal rows matched so far.
started_atstring | nullISO 8601 start timestamp.
completed_atstring | nullISO 8601 completion timestamp (null while in progress).

Response (GET /progress)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "running",
  "phase": "scoring",
  "phase_progress": 64.5,
  "rows_processed": 129,
  "rows_matched": 105,
  "started_at": "2024-10-02T14:00:05.000Z",
  "completed_at": null
}
POST/v1/matching/runs/:id/ai-resolve

Response (AI Resolve)

Response fields

idstringRun UUID.
statusstringUpdated status: ai_resolving.
messagestringHuman-readable confirmation message.

Response (POST /ai-resolve)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "ai_resolving",
  "message": "AI resolution started. Poll the run detail endpoint for progress."
}

Errors

Error responses

400validation_errorThe run does not have a strategy_id (required for ai-resolve).
401unauthorizedMissing or invalid API key.
404not_foundNo matching run with this ID exists for your workspace.
409conflictThe run cannot be cancelled because it has already completed, failed, or been cancelled.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Run Matching
Run Detail
Results