Skip to main content

Schema Summary

Get structuring quality metrics for a schema: capture hit rate, synthesize rate, unresolved rate, strategy distribution, and per-field state breakdown.

Telemetry endpoints report structuring quality metrics: how many cells were filled deterministically from the field registry (captured), how many needed LLM synthesis, and how many stayed unresolved. The schema summary aggregates these metrics from the latest run of a schema. Use it to track extraction cost efficiency and to spot schemas whose fields the registry has not yet learned.

Every cell in a run resolves to one of four states, and the summary reports both the raw counts (tier_distribution — the payload field keeps its historical "tier" name, but its keys are these four cell states, not field registry maturity levels) and the derived rates:

  • captured — Filled deterministically (registry transfer, reference lookup, compute, or constant) without an LLM call. capture_hit_rate is the captured share of all cells. Higher is more cost-efficient.
  • extracted — Filled by schema-targeted extraction.
  • synthesized — Filled by LLM synthesis. synthesize_rate is the synthesized share of all cells and the main cost driver.
  • unresolved — Left empty because no strategy produced a value. unresolved_rate is the unresolved share.

The response also includes strategy_distribution (how many schema fields are configured with each fill strategy, such as constant, generator, reference, or compute; fields without an explicit strategy count under none) and a per_field array with each field's unresolved_rate and cell-state counts. Use per_field to find the specific fields dragging the aggregate rates down.

If the schema has no completed runs yet, the endpoint returns 200 with { "data": null, "message": "No runs found for this schema." } rather than a 404. A 404 means the schema ID itself does not exist in your organization.
GET/v1/telemetry/schemas/{id}/summary

Response

Response fields

run_idstringUUID of the latest run used for this summary.
schema_idstringSchema UUID.
total_fieldsintegerNumber of fields in the schema snapshot.
total_recordsintegerNumber of records (rows) in the run.
strategy_distributionobjectCount of schema fields per configured fill strategy (e.g. none, constant, generator, reference, compute).
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 for the run.
per_field[].field_namestringSchema field name.
per_field[].unresolved_ratenumberFraction of this field's cells left unresolved (0-1).
per_field[].state_distributionobjectCell counts per state for this field (captured, extracted, synthesized, unresolved).

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 }
    },
    {
      "field_name": "payment_terms",
      "unresolved_rate": 0.14,
      "state_distribution": { "captured": 54, "synthesized": 32, "unresolved": 14 }
    }
  ]
}

Errors

Error responses

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

Related

Schema Trend
Schema Fields
Run Summary