Skip to main content

Get Resolution

Retrieve a resolution run by UUID: lifecycle status, frozen policy and dialect snapshots, error detail on failure, and links to results and the source job.

Retrieve the current state of a specific resolution run by its UUID. The response carries the run's lifecycle status (pending, processing, completed, or failed), the frozen policy_snapshot and dialect_snapshot it was created with, an error_message when the run failed, and a links object pointing at the results endpoint and the source job run. Use this endpoint as the polling target after executing a resolution.

The updated_at timestamp moves on every status transition, so status plus updated_at is enough to build a robust poller: treat completed and failed as terminal, keep polling while the run is processing, and alert if a run sits in processing without an updated_at change for far longer than your usual run time. On failure, error_message carries the terminal error detail — the first thing to read before retrying.

The snapshots answer "what configuration did this run actually use": policy_snapshot.fields lists every field with the reference table, compute expression, modifiers, and format constraints that were in force when the run was created, and policy_snapshot.name is the run's auto-generated display name. Because later edits to your rules never touch existing snapshots, this is the authoritative record for auditing a normalization outcome after the configuration has moved on.

The links object saves you URL construction: links.results points at the per-field results read, and links.source_run points back at the job run (/v1/jobs/{source_run_id}) whose extracted values this resolution normalizes. When you hold only a resolution id — say, from a stored reference in your own system — one GET here recovers the whole context: what ran, over which job, under which configuration, and where the output lives.

GET/v1/resolutions/{id}

Path parameters

id*uuidResolution run UUID.

curl

curl -s https://api.talonic.com/v1/resolutions/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

idstringResolution run UUID.
source_run_idstringUUID of the originating job run.
statusstringRun status: pending, processing, completed, or failed.
policy_snapshotobject | nullFrozen normalization config: name, sanity_check, and per-field rules (reference tables, modifiers, constraints, format rules).
dialect_snapshotobject | nullFrozen dialect configuration at creation, or null when the schema has no dialect wired.
error_messagestring | nullTerminal error detail when status is failed; null otherwise.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 timestamp of the last status transition.
linksobjectRelated resource URLs: self, results, source_run.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "completed",
  "policy_snapshot": {
    "name": "Resolution 42Docs Jul 14",
    "sanity_check": false,
    "fields": [
      {
        "field_name": "country",
        "display_name": "Country",
        "data_type": "string",
        "reference_table": "iso-countries",
        "modifiers": null,
        "format": null,
        "suppress_output": false,
        "output_name": null
      }
    ]
  },
  "dialect_snapshot": null,
  "error_message": null,
  "created_at": "2026-07-14T10:32:00.000Z",
  "updated_at": "2026-07-14T10:35:42.000Z",
  "links": {
    "self": "/v1/resolutions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "results": "/v1/resolutions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/results",
    "source_run": "/v1/jobs/b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}
Poll at a modest interval (every few seconds) — polling is metered under the general read namespace of your daily quota. Deterministic policy rules finish in seconds; runs whose policy invokes LLM-assisted matching for ambiguous values can take several minutes.

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundResolution run not found or does not belong to your organization.
429rate_limitedDaily request quota for your tier reached. The counter resets at midnight UTC.

Frequently asked questions

How long does a resolution run typically take?+
Runs whose rules are purely deterministic (lookups, computes, format constraints) finish in seconds. Runs whose policy requires LLM-assisted matching for ambiguous values take longer — typically 1-5 minutes depending on how many values need model calls.
What does a failed resolution status mean?+
The pipeline hit a terminal error; the detail is in error_message. A failed run can be re-executed in place with POST /v1/resolutions/{id}/execute — you do not need to delete and recreate it unless you want a fresh configuration snapshot.
How do I see which configuration a run used?+
Read policy_snapshot on this response: its fields array lists every field with the reference table, compute expression, modifiers, and format constraints in force when the run was created. Later rule edits never rewrite existing snapshots, so this is the audit record for the run's outcome.
How do I know when to stop polling?+
Stop on completed or failed — both are terminal. While processing, updated_at advances on status transitions; a run stuck in processing far beyond your normal run time with no updated_at movement is worth flagging rather than polling forever.

Related

List Resolutions
Execute Resolution
Get Resolution Results
Delete Resolution
Get Job