Skip to main content

Schema Fields

Get per-field structuring metrics for a schema: unresolved rate, alias fire count, and reference miss rate. Identify fields that need instruction tuning.

Per-field telemetry drills into individual field performance within a schema, computed from the latest run. For each schema field it reports the unresolved_rate (how often the field stayed empty), the alias_fire_count (how many times an alias modifier normalized the value), and the reference_miss_rate (how often reference-data lookups for the field missed). Use it to identify underperforming fields that need instruction tuning, alias additions, or reference-data fixes.

Call this endpoint after reviewing the [Schema Summary](schema-telemetry-summary) to investigate which fields are driving a high aggregate unresolved_rate. The field-level breakdown reveals whether issues are concentrated in a few problematic fields or spread evenly across the schema. For per-field cell-state counts (captured vs. synthesized), use the per_field array in the summary response.

A high reference_miss_rate means values are failing to match your uploaded reference data: check for formatting differences or missing rows in the reference table. A zero alias_fire_count on a field with configured aliases means the aliases never matched, which usually indicates they are stale.

Fields with a persistently high unresolved_rate across runs are strong candidates for adding explicit extraction instructions, configuring a fill strategy (constant, reference, compute), or enriching the field registry with example values.
GET/v1/telemetry/schemas/{id}/fields

Response

Response fields

dataarrayArray of per-field telemetry objects, one per schema field.
data[].field_namestringSchema field name.
data[].unresolved_ratenumberFraction of records where this field could not be filled (0-1).
data[].alias_fire_countintegerNumber of times an alias modifier fired for this field in the run.
data[].reference_miss_ratenumberFraction of reference-data lookups for this field that missed (0-1). Zero when the field uses no reference lookups.

Response

{
  "data": [
    {
      "field_name": "invoice_number",
      "unresolved_rate": 0.02,
      "alias_fire_count": 12,
      "reference_miss_rate": 0
    },
    {
      "field_name": "payment_terms",
      "unresolved_rate": 0.14,
      "alias_fire_count": 0,
      "reference_miss_rate": 0.21
    }
  ]
}

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.

Frequently asked questions

What does a high unresolved_rate for a field mean?+
The field could not be filled in many records. This may indicate the field is not present in those document types, the extraction instructions need refinement, or no fill strategy is configured for it.
What is the alias_fire_count?+
The number of times an alias modifier fired for that field during the latest run, i.e. how often a raw value was normalized through a configured alias mapping. A zero count on a field with aliases suggests the aliases no longer match real values.
What does reference_miss_rate measure?+
The fraction of reference-data lookup operations for the field that failed to find a match. A high miss rate usually means formatting differences between extracted values and your reference table, or missing rows in the reference data.
Where do I find per-field captured vs. synthesized counts?+
In the per_field array of the Schema Summary response (GET /v1/telemetry/schemas/{id}/summary), which includes a state_distribution object per field with captured, extracted, synthesized, and unresolved counts.

Related

Schema Summary
Schema Trend
Reference Data Rows & Export