Skip to main content

Run Summary

Get structuring metrics for a single job run: capture hit rate, synthesize rate, tier distribution, and per-field breakdown. Compare runs side by side.

The run telemetry summary returns structuring metrics for a specific job run rather than the latest run of a schema. Use it to inspect the performance of a particular execution, compare two runs side by side, or debug a run that produced unexpected results. The response shape is identical to the Schema Summary.

The typical workflow is to list your job runs, then call this endpoint with the run UUID to inspect its metrics. When a run produces unexpected accuracy, the telemetry reveals whether the issue is in capture (registry gaps show up as a low capture_hit_rate), synthesis (a high synthesize_rate means heavy LLM dependence), or coverage (a high unresolved_rate).

The schema_id field identifies which schema was used, letting you cross-reference with the schema-level trend and per-field telemetry. To compare two runs, call this endpoint twice with different run IDs and diff the tier_distribution and per_field values. Use the Schema Trend endpoint when you need the full historical view rather than a point-in-time comparison.

Telemetry is computed from the results written so far. Calling this endpoint on a run that is still in progress returns partial metrics that change as more records complete; a 404 means the run ID does not exist for your organization.
GET/v1/telemetry/runs/{id}/summary

Response

Response fields

run_idstringThe job run UUID.
schema_idstringUUID of the schema used for this run.
total_fieldsintegerNumber of fields in the schema snapshot.
total_recordsintegerNumber of records in the run.
strategy_distributionobjectCount of schema fields per configured fill strategy.
tier_distributionobjectCell counts per resolution state: captured, extracted, synthesized, unresolved.
capture_hit_ratenumberFraction of cells filled deterministically without an LLM call (0-1).
synthesize_ratenumberFraction of cells filled via LLM synthesis (0-1).
unresolved_ratenumberFraction of cells left unresolved (0-1).
per_fieldarrayPer-field breakdown (field_name, unresolved_rate, state_distribution).

Response

{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schema_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "total_fields": 20,
  "total_records": 100,
  "strategy_distribution": {
    "none": 14,
    "compute": 2,
    "reference": 2,
    "constant": 1,
    "generator": 1
  },
  "tier_distribution": {
    "captured": 1440,
    "extracted": 200,
    "synthesized": 300,
    "unresolved": 60
  },
  "capture_hit_rate": 0.72,
  "synthesize_rate": 0.15,
  "unresolved_rate": 0.03,
  "per_field": [
    {
      "field_name": "invoice_number",
      "unresolved_rate": 0.02,
      "state_distribution": { "captured": 96, "extracted": 2, "unresolved": 2 }
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundNo job run with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

How do I compare two runs?+
Call this endpoint twice with different run IDs and compare the capture_hit_rate, synthesize_rate, unresolved_rate, and tier_distribution values. The per_field arrays show which specific fields improved or regressed between the runs.
Can I get telemetry for a run that is still in progress?+
Yes, but the metrics are partial: telemetry is computed from the results written so far, so the numbers change until the run completes. A 404 is only returned when the run ID does not exist for your organization.
How is the run summary different from the schema summary?+
The response shape is identical. The schema summary always reports on the latest run of a schema, while the run summary targets one specific run by its UUID, which is what you need for side-by-side comparisons or debugging a past execution.