Operational KPI Driver Rows
Return the strict producer-owned operational KPI driver row DTO without transport reinterpretation.
Tier: paid | Cache: cold-allowed | Playground: authenticated only | Contract: 1.1.0
When To Use It
Use these tools for operational metrics that are not consistently modeled as standard XBRL financial concepts.
Request Examples
BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
curl -sS -G "$BASE_URL/api/operational-kpis/drivers" \
-H "Authorization: Bearer $EDGAR_API_KEY" \
--data-urlencode "ticker=AAPL" \
--data-urlencode "year=2025" \
--data-urlencode "quarter=4"import os
import requests
base_url = os.getenv("EDGAR_API_URL", "https://www.edgarparser.com")
headers = {"Authorization": f"Bearer {os.environ['EDGAR_API_KEY']}"}
params = {
"ticker": "AAPL",
"year": 2025,
"quarter": 4
}
response = requests.get(f"{base_url}/api/operational-kpis/drivers", headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()Key Response Fields
| Field | Type | Why It Matters |
|---|---|---|
status | const "success" | Transport-level success indicator inside the JSON response. |
semantic_status | "ok" | "partial" | "empty" | "error" | null | Whether the response is semantically usable, partial, empty, or errored. |
coverage_status | "complete" | "partial" | "narrow" | "none" | null | Completeness signal; do not present partial or narrow coverage as complete. |
coverage_warning | string | null | Human-readable explanation of missing or ambiguous coverage. |
rows | array<object> | Tabular or comparison rows that carry the answer data. |
contract_version | const "edgar-operational-kpi-driver-rows.v1" | Extraction result field; inspect provenance and coverage before treating it as disclosed. |
producer_id | const "edgar_updater" | Stable identifier for follow-up calls or source attribution. |
quarter | integer | Extraction result field; inspect provenance and coverage before treating it as disclosed. |
Response Fields To Inspect
- Driver name, value, units, period, and source evidence before using a KPI in an answer.
- Coverage or provenance fields when a KPI comes from narrative disclosures.
- Directional and period-comparison fields before describing a trend.
Errors And Coverage
401or403: the API key is missing, expired, or not allowed to use this tier.429: retry after the rate-limit window, and prefer broader batch or series tools over repeated single-period calls.- Cold work can take longer and may queue background fetch or parse work; use status fields or follow-up tools before finalizing.
- Paid or LLM-backed paths should be used only when cheaper fact, filing, table, or text tools cannot answer the question.
- Treat partial coverage, empty arrays, and warning fields as answer-quality signals even when HTTP status is
200.
Related Tools
Operational KPI Drivers, Filing Extractions, Search Extractions
Generated Reference
Contract
| Field | Value |
|---|---|
| Tool | get_operational_kpi_driver_rows |
| Method | GET |
| Path | /api/operational-kpis/drivers |
| Contract version | 1.1.0 |
Parameters
| Name | Location | Required | Type | Notes |
|---|---|---|---|---|
ticker | query | yes | string | |
year | query | yes | integer | |
quarter | query | yes | integer | |
source | query | no | string | null | |
topic | query | no | string | null | |
filter_to_topic | query | no | boolean | |
include_non_numeric | query | no | boolean |
Response Schema (200)
{
"additionalProperties": true,
"properties": {
"contract_version": {
"const": "edgar-operational-kpi-driver-rows.v1",
"type": "string"
},
"coverage_status": {
"anyOf": [
{
"enum": [
"complete",
"partial",
"narrow",
"none"
],
"type": "string"
},
{
"type": "null"
}
]
},
"coverage_warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"producer_id": {
"const": "edgar_updater",
"type": "string"
},
"quarter": {
"maximum": 4.0,
"minimum": 1.0,
"type": "integer"
},
"row_count": {
"minimum": 0.0,
"type": "integer"
},
"rows": {
"items": {
"additionalProperties": true,
"properties": {
"calculation_ready": {
"type": "boolean"
},
"class_hint": {
"minLength": 1,
"type": "string"
},
"contract_version": {
"const": "edgar-kpi-observation.v2",
"type": "string"
},
"display": {
"additionalProperties": true,
"type": "object"
},
"factors": {
"items": {
"enum": [
"volume",
"price",
"unit_economics",
"cost_structure",
"reinvestment",
"capital_sources"
],
"type": "string"
},
"minItems": 1,
"type": "array"
},
"grounded": {
"type": "boolean"
},
"kind": {
"enum": [
"metric_value",
"growth_rate"
],
"type": "string"
},
"metric_kind": {
"enum": [
"absolute",
"growth",
"ratio",
"index"
],
"type": "string"
},
"metric_name": {
"minLength": 1,
"type": "string"
},
"metric_name_normalized": {
"minLength": 1,
"type": "string"
},
"period": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"period_frame": {
"anyOf": [
{
"enum": [
"annual",
"quarterly",
"ttm",
"ytd",
"point_in_time"
],
"type": "string"
},
{
"type": "null"
}
]
},
"period_year": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"producer_id": {
"const": "edgar_updater",
"type": "string"
},
"producer_version": {
"const": "numeric-prose.v2",
"type": "string"
},
"recommended_for_calculation": {
"type": "boolean"
},
"scale": {
"enum": [
"unit",
"thousands",
"millions",
"billions"
],
"type": "string"
},
"segment": {
"minLength": 1,
"type": "string"
},
"segment_binding": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"axis": {
"minLength": 1,
"type": "string"
},
"axis_family": {
"enum": [
"segment",
"product",
"geography",
"other"
],
"type": "string"
},
"member": {
"minLength": 1,
"type": "string"
},
"segment_label": {
"minLength": 1,
"type": "string"
}
},
"required": [
"axis",
"member",
"axis_family",
"segment_label"
],
"type": "object"
},
{
"type": "null"
}
]
},
"unit": {
"enum": [
"dollars",
"percentage",
"ratio",
"count",
"share_count",
"per_share",
"days",
"date",
"multiple",
"unknown"
],
"type": "string"
},
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"value_normalized": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"value_raw": {
"type": "string"
},
"value_semantic": {
"enum": [
"growth_rate",
"period_absolute_value"
],
"type": "string"
},
"value_status": {
"enum": [
"numeric",
"directional",
"non_numeric"
],
"type": "string"
}
},
"required": [
"kind",
"metric_name",
"metric_name_normalized",
"class_hint",
"metric_kind",
"factors",
"segment",
"segment_binding",
"period",
"period_year",
"period_frame",
"value",
"value_normalized",
"value_raw",
"value_semantic",
"display",
"recommended_for_calculation",
"contract_version",
"producer_id",
"producer_version",
"grounded",
"value_status",
"calculation_ready",
"unit",
"scale"
],
"type": "object"
},
"type": "array"
},
"semantic_status": {
"anyOf": [
{
"enum": [
"ok",
"partial",
"empty",
"error"
],
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"enum": [
"auto",
"8k",
"proxy",
"20f",
"6k"
],
"type": "string"
},
"status": {
"const": "success",
"type": "string"
},
"ticker": {
"minLength": 1,
"type": "string"
},
"year": {
"type": "integer"
}
},
"required": [
"contract_version",
"producer_id",
"status",
"ticker",
"year",
"quarter",
"source",
"row_count"
],
"type": "object"
}