Get match run

Use this endpoint to retrieve the details of a specific match run by its identifier. The response includes status, timing, and aggregate statistics.

GET /v1/matching/runs/{runId}

Get match run

cURL

curl --request GET \
  --url https://matcher.sandbox.lerian.net/v1/matching/runs/{runId} \
  --header 'Authorization: Bearer <token>'

200

Example

{
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2025-01-15T10:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mode": "DRY_RUN",
  "startedAt": "2025-01-15T10:30:00Z",
  "status": "COMPLETED",
  "updatedAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:35:00Z",
  "failureReason": "no matching rules found",
  "ruleStats": [
    {
      "matched": 42,
      "priority": 1,
      "ruleId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "EXACT"
    }
  ],
  "stats": {}
}

Autorizaciones

Authorization · string · header · requerido

Bearer token authentication (format: "Bearer {token}")

Encabezados

X-Request-Id · string

A unique identifier for tracing the request across services.

Parámetros de ruta

runId · string<uuid> · requerido

Run ID

Parámetros de consulta

contextId · string<uuid>

Context ID Context ID the run belongs to. Optional: when omitted the run is resolved by id within the tenant.

Respuesta

200

application/json

Indicates that the request was successful and the response contains the expected data.

contextId · string · requerido

Reconciliation context ID this run belongs to

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

createdAt · string · requerido

Creation timestamp (RFC 3339)

Ejemplo:

"2025-01-15T10:30:00Z"

id · string · requerido

Unique identifier for the run

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

mode · enum<string> · requerido

Execution mode: DRY_RUN evaluates rules without committing matches; COMMIT persists matches

Opciones disponibles: DRY_RUN, COMMIT

Ejemplo:

"DRY_RUN"

startedAt · string · requerido

When the run started (RFC 3339 timestamp)

Ejemplo:

"2025-01-15T10:30:00Z"

status · enum<string> · requerido

Current status of the run: QUEUED (async submit, awaiting worker pickup), PROCESSING (in flight), FINALIZING (a transient finishing-up state — a poll MAY briefly observe it between PROCESSING and COMPLETED, and it is also observable while a run is recovered after a crash; treat it as in-flight, not terminal), COMPLETED (finished), or FAILED (errored). An async run in flight when its pod stops goes back from PROCESSING to QUEUED and is picked up again with a new startedAt

Opciones disponibles: QUEUED, PROCESSING, FINALIZING, COMPLETED, FAILED

Ejemplo:

"COMPLETED"

updatedAt · string · requerido

Last update timestamp (RFC 3339)

Ejemplo:

"2025-01-15T10:30:00Z"

completedAt · string

When the run completed (RFC 3339 timestamp); absent until the run finishes

Ejemplo:

"2025-01-15T10:35:00Z"

failureReason · string

Failure reason; present only when the run status is FAILED

Ejemplo:

"no matching rules found"

ruleStats · object[] | null

Structured per-rule matched group counts frozen at run completion. Every rule configured at run time appears, including zero-match rules, and the matched counts sum to the run's matches stat. Absent on runs completed before the keys were introduced

Show child attributes

stats · object

Aggregate run statistics as an open key-value map; consumers must tolerate unknown keys and treat a missing key as unknown rather than zero. Known keys include matches, candidates_left, candidates_right, unmatched_left, unmatched_right, unmatched_external, auto_matched_left, auto_matched_right, pending_review_left, pending_review_right, proposed_left, proposed_right, exceptions_raised (newly created), exceptions_updated (re-touched), plus per-rule families rule_matched: and rule_meta::. A run recovered after an interruption reports the exception rows its earlier attempt created under exceptions_updated, not exceptions_raised

Show child attributes