Metric Series
Return one metric across multiple periods with per-period cache and coverage status.
Tier: public | Cache: cache-only | Playground: anonymous playground | Contract: 1.1.0
When To Use It
Use these tools when the model needs normalized financial facts, concept-level series, or statement-shaped outputs grounded in XBRL.
Request Examples
BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
curl -sS -G "$BASE_URL/api/metric/series" \
-H "Authorization: Bearer $EDGAR_API_KEY" \
--data-urlencode "ticker=AAPL" \
--data-urlencode "metric_name=Revenue" \
--data-urlencode "end_year=2025" \
--data-urlencode "end_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",
"metric_name": "Revenue",
"end_year": 2025,
"end_quarter": 4
}
response = requests.get(f"{base_url}/api/metric/series", headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()Key Response Fields
| Field | Type | Why It Matters |
|---|---|---|
status | "success" | "partial" | "error" | 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. |
cache_miss | boolean | null | Financial fact or concept field; inspect unit, period, and source context before using it. |
contract_version | const "edgar-metric-series.v1" | Financial fact or concept field; inspect unit, period, and source context before using it. |
date_type | string | null | Financial fact or concept field; inspect unit, period, and source context before using it. |
full_year_mode | boolean | Financial fact or concept field; inspect unit, period, and source context before using it. |
Response Fields To Inspect
status/semantic_statusfor whether the tool produced a usable fact set.coverage_statusandcoverage_warningbefore treating the value as complete.source_ref, concept names, units, and period metadata for citation and auditability.
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.- Playground traffic is cache-only and scope-limited; a structured
403cache miss means the requested filing or period is not warm for anonymous use. - Treat partial coverage, empty arrays, and warning fields as answer-quality signals even when HTTP status is
200.
Related Tools
Metric, Search Metrics, Warm Metric Cache
Generated Reference
Contract
| Field | Value |
|---|---|
| Tool | get_metric_series |
| Method | GET |
| Path | /api/metric/series |
| Contract version | 1.1.0 |
Parameters
| Name | Location | Required | Type | Notes |
|---|---|---|---|---|
ticker | query | yes | string | |
metric_name | query | yes | string | |
end_year | query | yes | integer | |
end_quarter | query | yes | integer | |
periods | query | no | integer | |
full_year_mode | query | no | boolean | |
source | query | no | string | |
date_type | query | no | string | null | |
include_equivalents | query | no | boolean | |
cached_only | query | no | boolean | |
role | query | no | string | null | |
axis_key | query | no | string | null |
Response Schema (200)
{
"additionalProperties": true,
"properties": {
"cache_miss": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"contract_version": {
"const": "edgar-metric-series.v1",
"type": "string"
},
"coverage_status": {
"anyOf": [
{
"enum": [
"complete",
"partial",
"narrow",
"none"
],
"type": "string"
},
{
"type": "null"
}
]
},
"coverage_warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"date_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"full_year_mode": {
"type": "boolean"
},
"metric_name": {
"type": "string"
},
"periods_cached": {
"type": "integer"
},
"periods_failed": {
"type": "integer"
},
"periods_fetched": {
"type": "integer"
},
"periods_missing": {
"type": "integer"
},
"periods_requested": {
"type": "integer"
},
"periods_returned": {
"type": "integer"
},
"periods_uncached": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"semantic_status": {
"anyOf": [
{
"enum": [
"ok",
"partial",
"empty",
"error"
],
"type": "string"
},
{
"type": "null"
}
]
},
"series": {
"items": {
"additionalProperties": true,
"properties": {
"axis_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"calculation_ready": {
"type": "boolean"
},
"contract_version": {
"const": "edgar-metric-series-entry.v1",
"type": "string"
},
"date_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"dimensions": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
]
},
"equivalence_group_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"filing_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metric_tag": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"period": {
"type": "string"
},
"period_end": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"period_ref": {
"discriminator": {
"mapping": {
"calendar_year": "#/components/schemas/CalendarYearPeriod",
"date": "#/components/schemas/DatePeriod",
"fiscal_quarter": "#/components/schemas/FiscalQuarterPeriod",
"fiscal_year": "#/components/schemas/FiscalYearPeriod",
"period_range": "#/components/schemas/PeriodRange"
},
"propertyName": "kind"
},
"oneOf": [
{
"additionalProperties": false,
"properties": {
"fiscal_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "fiscal_year",
"type": "string"
}
},
"required": [
"kind",
"fiscal_year"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"fiscal_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "fiscal_quarter",
"type": "string"
},
"quarter": {
"maximum": 4.0,
"minimum": 1.0,
"type": "integer"
}
},
"required": [
"kind",
"fiscal_year",
"quarter"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"date": {
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
"type": "string"
},
"kind": {
"const": "date",
"type": "string"
}
},
"required": [
"kind",
"date"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"calendar_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "calendar_year",
"type": "string"
}
},
"required": [
"kind",
"calendar_year"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"end": {
"discriminator": {
"mapping": {
"calendar_year": "#/components/schemas/CalendarYearPeriod",
"date": "#/components/schemas/DatePeriod",
"fiscal_quarter": "#/components/schemas/FiscalQuarterPeriod",
"fiscal_year": "#/components/schemas/FiscalYearPeriod",
"period_range": "#/components/schemas/PeriodRange"
},
"propertyName": "kind"
},
"oneOf": [
{
"additionalProperties": false,
"properties": {
"fiscal_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "fiscal_year",
"type": "string"
}
},
"required": [
"kind",
"fiscal_year"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"fiscal_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "fiscal_quarter",
"type": "string"
},
"quarter": {
"maximum": 4.0,
"minimum": 1.0,
"type": "integer"
}
},
"required": [
"kind",
"fiscal_year",
"quarter"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"date": {
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
"type": "string"
},
"kind": {
"const": "date",
"type": "string"
}
},
"required": [
"kind",
"date"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"calendar_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "calendar_year",
"type": "string"
}
},
"required": [
"kind",
"calendar_year"
],
"type": "object"
},
{
"$ref_cycle": "#/components/schemas/PeriodRange"
}
]
},
"kind": {
"const": "period_range",
"type": "string"
},
"start": {
"discriminator": {
"mapping": {
"calendar_year": "#/components/schemas/CalendarYearPeriod",
"date": "#/components/schemas/DatePeriod",
"fiscal_quarter": "#/components/schemas/FiscalQuarterPeriod",
"fiscal_year": "#/components/schemas/FiscalYearPeriod",
"period_range": "#/components/schemas/PeriodRange"
},
"propertyName": "kind"
},
"oneOf": [
{
"additionalProperties": false,
"properties": {
"fiscal_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "fiscal_year",
"type": "string"
}
},
"required": [
"kind",
"fiscal_year"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"fiscal_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "fiscal_quarter",
"type": "string"
},
"quarter": {
"maximum": 4.0,
"minimum": 1.0,
"type": "integer"
}
},
"required": [
"kind",
"fiscal_year",
"quarter"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"date": {
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
"type": "string"
},
"kind": {
"const": "date",
"type": "string"
}
},
"required": [
"kind",
"date"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"calendar_year": {
"maximum": 2200.0,
"minimum": 1900.0,
"type": "integer"
},
"kind": {
"const": "calendar_year",
"type": "string"
}
},
"required": [
"kind",
"calendar_year"
],
"type": "object"
},
{
"$ref_cycle": "#/components/schemas/PeriodRange"
}
]
}
},
"required": [
"kind",
"start",
"end"
],
"type": "object"
}
]
},
"period_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"presentation_roles": {
"items": {
"type": "string"
},
"type": "array"
},
"prior_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
]
},
"quantity": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"display": {
"additionalProperties": false,
"properties": {
"currency": {
"anyOf": [
{
"maxLength": 3,
"minLength": 3,
"type": "string"
},
{
"type": "null"
}
]
},
"denominator_basis": {
"anyOf": [
{
"enum": [
"nav",
"gross_exposure",
"net_exposure",
"portfolio_value",
"total_market_value",
"benchmark_total",
"fund_total"
],
"type": "string"
},
{
"type": "null"
}
]
},
"numeric_kind": {
"enum": [
"currency",
"percentage",
"basis_points",
"multiple",
"count",
"per_share",
"ratio",
"index",
"duration",
"date",
"weight"
],
"type": "string"
},
"precision": {
"default": 1,
"maximum": 8.0,
"minimum": 0.0,
"type": "integer"
},
"scale": {
"default": "unit",
"enum": [
"unit",
"thousands",
"millions",
"billions"
],
"type": "string"
},
"unit_label": {
"anyOf": [
{
"minLength": 1,
"pattern": "^[^\\u0000-\\u001F\\u007F-\\u009F]+$",
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"numeric_kind"
],
"type": "object"
},
"value": {
"pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$",
"type": "string"
}
},
"required": [
"value",
"display"
],
"type": "object"
},
{
"type": "null"
}
]
},
"quarter": {
"type": "integer"
},
"scale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"semantic_error": {
"anyOf": [
{
"enum": [
"unit_unavailable",
"value_unavailable"
],
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source_identity": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"accession": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"equivalence_group_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fact_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metric_tag": {
"minLength": 1,
"type": "string"
},
"producer_id": {
"const": "edgar_updater",
"type": "string"
},
"requested_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"producer_id",
"metric_tag"
],
"type": "object"
},
{
"type": "null"
}
]
},
"statement_position": {
"default": "aggregate",
"enum": [
"aggregate",
"dimensional"
],
"type": "string"
},
"statement_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"statement_roles": {
"items": {
"type": "string"
},
"type": "array"
},
"status": {
"enum": [
"ok",
"missing",
"locked",
"error"
],
"type": "string"
},
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
]
},
"year": {
"type": "integer"
},
"yoy_change_pct": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"contract_version",
"period",
"period_ref",
"year",
"quarter",
"calculation_ready",
"status"
],
"type": "object"
},
"type": "array"
},
"status": {
"enum": [
"success",
"partial",
"error"
],
"type": "string"
},
"ticker": {
"type": "string"
},
"warm_hint": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
}
},
"required": [
"contract_version",
"status",
"ticker",
"metric_name",
"full_year_mode",
"periods_requested",
"periods_returned",
"periods_cached",
"periods_fetched",
"periods_failed",
"periods_missing"
],
"type": "object"
}