Skip to main content

Schema Trend

Get metric trends over time for a schema. Returns time-series telemetry data across recent runs for tracking quality changes.

Track how structuring metrics evolve over successive runs for a schema. This endpoint returns a time-series of telemetry snapshots, allowing you to detect quality improvements, regressions, or shifts in strategy distribution as your field registry matures.

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.

Each snapshot in the data array contains the same metrics as the Schema Summary — capture_hit_rate, synthesize_rate, strategy_distribution, and tier_funnel — plus a created_at timestamp and run_id. The array is ordered by most recent run first.

Compare the trend data with the Schema 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

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[].capture_hit_ratenumberFraction of cells filled via registry capture for this run.
data[].synthesize_ratenumberFraction of cells filled via LLM synthesis for this run.
data[].strategy_distributionobjectStrategy counts for this run.
data[].tier_funnelobjectTier funnel counts for this run.

Response

{
  "data": [
    {
      "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2024-09-14T10:00:00.000Z",
      "capture_hit_rate": 0.72,
      "synthesize_rate": 0.18,
      "strategy_distribution": {
        "transfer": 1240,
        "extract": 310,
        "compute": 88,
        "skip": 22
      },
      "tier_funnel": {
        "tier1": 840,
        "tier2": 400,
        "tier3": 200,
        "unresolved": 220
      }
    },
    {
      "run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "created_at": "2024-09-07T10:00:00.000Z",
      "capture_hit_rate": 0.68,
      "synthesize_rate": 0.21,
      "strategy_distribution": {
        "transfer": 1180,
        "extract": 360,
        "compute": 84,
        "skip": 36
      },
      "tier_funnel": {
        "tier1": 800,
        "tier2": 380,
        "tier3": 180,
        "unresolved": 300
      }
    }
  ]
}

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