Skip to main content

Schema Trend

Track structuring metrics over time for a schema. Returns a time-series of capture hit rate, synthesize rate, and unresolved rate across recent runs.

The schema telemetry trend endpoint returns a time-series of structuring metrics across the most recent runs of a schema, newest first. Each snapshot carries the same metrics as the [Schema Summary](schema-telemetry-summary): capture hit rate, synthesize rate, unresolved rate, strategy distribution, tier distribution, and per-field breakdown, plus the run_id and created_at timestamp. Use it to detect quality regressions or confirm that the field registry is maturing.

Call this endpoint after several extraction runs to build trend charts or to detect regressions. The default window returns the 10 most recent runs; use the window query parameter to expand up to 50 runs for longer-term analysis. Values outside 1-50 are clamped, not rejected.

Compare the trend data with the [Schema Fields](schema-telemetry-fields) endpoint to pinpoint which specific fields are driving changes. A sudden spike in synthesize_rate across runs may indicate a new document type that the field registry has not yet learned, while a steady decrease signals healthy registry maturation.

A rising capture_hit_rate over time indicates the field registry is learning from extractions and resolving more fields deterministically, reducing LLM costs.
GET/v1/telemetry/schemas/{id}/trend

Query parameters

windowintegerNumber of recent runs to include (default 10, min 1, max 50; out-of-range values are clamped).

Response

Response fields

dataarrayArray of per-run telemetry snapshots ordered by most recent first.
data[].run_idstringRun UUID.
data[].created_atstringISO 8601 timestamp when the run was created.
data[].total_fieldsintegerNumber of schema fields in this run.
data[].total_recordsintegerNumber of records in this run.
data[].capture_hit_ratenumberFraction of cells filled deterministically for this run (0-1).
data[].synthesize_ratenumberFraction of cells filled via LLM synthesis for this run (0-1).
data[].unresolved_ratenumberFraction of cells left unresolved for this run (0-1).
data[].strategy_distributionobjectField counts per configured fill strategy for this run.
data[].tier_distributionobjectCell counts per resolution state (captured, extracted, synthesized, unresolved).
data[].per_fieldarrayPer-field state breakdown for this run (field_name, unresolved_rate, state_distribution).

Response

{
  "data": [
    {
      "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2024-09-14T10:00:00.000Z",
      "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": "payment_terms",
          "unresolved_rate": 0.14,
          "state_distribution": { "captured": 54, "synthesized": 32, "unresolved": 14 }
        }
      ]
    },
    {
      "run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "created_at": "2024-09-07T10:00:00.000Z",
      "total_fields": 20,
      "total_records": 95,
      "strategy_distribution": { "none": 14, "compute": 2, "reference": 2, "constant": 1, "generator": 1 },
      "tier_distribution": { "captured": 1292, "extracted": 190, "synthesized": 342, "unresolved": 76 },
      "capture_hit_rate": 0.68,
      "synthesize_rate": 0.18,
      "unresolved_rate": 0.04,
      "per_field": [
        {
          "field_name": "payment_terms",
          "unresolved_rate": 0.2,
          "state_distribution": { "captured": 46, "synthesized": 30, "unresolved": 19 }
        }
      ]
    }
  ]
}

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 Summary
Schema Fields
Run Summary