Skip to main content

Schema Fields

Get per-field structuring metrics for a schema including field-level state distribution, capture rates, and strategy breakdown.

Drill down to individual field performance within a schema. This endpoint returns per-field capture rates, synthesis rates, the most common strategy used, and the distribution of cell states (filled, empty, skipped). Use it to identify underperforming fields that may need instruction tuning or manual review.

Call this endpoint after reviewing the Schema Summary to investigate which fields are driving low capture rates or high synthesis costs. The field-level breakdown reveals whether issues are concentrated in a few problematic fields or spread evenly across the schema.

Each entry in the data array includes the field_name, capture_rate and synthesize_rate (both 0-1 fractions), the dominant strategy (one of transfer, extract, compute, skip), and a state_distribution object with filled, empty, and skipped counts. Fields with a strategy of extract are LLM-dependent and contribute most to cost.

Pair this with the Schema Trend endpoint to track how individual field performance changes across runs. Fields that remain stuck on extract strategy after multiple runs are strong candidates for adding explicit instructions or seeding the field registry with example values.

Fields with a high synthesize_rate and low capture_rate are candidates for field registry enrichment or instruction refinement to reduce LLM dependency.
GET/v1/telemetry/schemas/{id}/fields

Response

Response fields

dataarrayArray of per-field telemetry objects.
data[].field_namestringField name.
data[].capture_ratenumberFraction of rows where this field was captured (0–1).
data[].synthesize_ratenumberFraction of rows where this field was synthesized by LLM (0–1).
data[].strategystringMost common strategy used for this field.
data[].state_distributionobjectCount of cells per state (filled, empty, skipped).

Response

{
  "data": [
    {
      "field_name": "invoice_number",
      "capture_rate": 0.98,
      "synthesize_rate": 0.01,
      "strategy": "transfer",
      "state_distribution": {
        "filled": 196,
        "empty": 2,
        "skipped": 2
      }
    },
    {
      "field_name": "payment_terms",
      "capture_rate": 0.54,
      "synthesize_rate": 0.38,
      "strategy": "extract",
      "state_distribution": {
        "filled": 184,
        "empty": 14,
        "skipped": 2
      }
    }
  ]
}

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 Trend