Search Metrics
Search filing metrics by natural-language query and return ranked exact candidates.
Tier: public | Cache: cold-allowed | Playground: authenticated only | Contract: 1.0.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/financials/search_metrics" \
-H "Authorization: Bearer $EDGAR_API_KEY" \
--data-urlencode "ticker=AAPL" \
--data-urlencode "year=2025" \
--data-urlencode "quarter=4" \
--data-urlencode "query=revenue recognition"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,
"query": "revenue recognition"
}
response = requests.get(f"{base_url}/api/financials/search_metrics", 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. |
matches | array<object> | Candidate fact matches; inspect labels, units, periods, and source references. |
confidence_reason | string | null | Financial fact or concept field; inspect unit, period, and source context before using it. |
date_type_filter | "Q" | "YTD" | "FY" | null | Financial fact or concept field; inspect unit, period, and source context before using it. |
debt_component_guidance | 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. |
hint | string | Financial fact or concept field; inspect unit, period, and source context before using it. |
low_confidence | 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.- Cold work can take longer and may queue background fetch or parse work; use status fields or follow-up tools before finalizing.
- Treat partial coverage, empty arrays, and warning fields as answer-quality signals even when HTTP status is
200.
Related Tools
List Metrics, Metric, Metric Series
Generated Reference
Contract
| Field | Value |
|---|---|
| Tool | search_metrics |
| Method | GET |
| Path | /api/financials/search_metrics |
| Contract version | 1.0.0 |
| Schema fingerprint | sha256:381c0bf743038780d55c447b0c7103da0e22d13c33b866c73130b7265071853c |
Parameters
| Name | Location | Required | Type | Notes |
|---|---|---|---|---|
ticker | query | yes | string | |
year | query | yes | integer | |
quarter | query | yes | integer | |
query | query | yes | string | |
full_year_mode | query | no | boolean | |
source | query | no | auto | 8k | |
date_type | query | no | Q | YTD | FY | null | |
role | query | no | array<string> | null | |
limit | query | no | integer | |
include_values | query | no | boolean |
Response Schema (200)
{
"additionalProperties": true,
"properties": {
"confidence_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"date_type_filter": {
"anyOf": [
{
"enum": [
"Q",
"YTD",
"FY"
],
"type": "string"
},
{
"type": "null"
}
]
},
"debt_component_guidance": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"full_year_mode": {
"type": "boolean"
},
"hint": {
"type": "string"
},
"low_confidence": {
"type": "boolean"
},
"matches": {
"items": {
"additionalProperties": true,
"properties": {
"axis_key": {
"default": "__NONE__",
"type": "string"
},
"concept_label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"current_value": {
"anyOf": [
{},
{
"type": "null"
}
]
},
"date_type": {
"anyOf": [
{
"enum": [
"Q",
"YTD",
"FY"
],
"type": "string"
},
{
"type": "null"
}
]
},
"debt_component_kind": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"dimensions": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
]
},
"has_value": {
"type": "boolean"
},
"match_confidence": {
"anyOf": [
{
"enum": [
"strong",
"fallback"
],
"type": "string"
},
{
"type": "null"
}
]
},
"match_score": {
"type": "number"
},
"matched_query_modifiers": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
},
"metric_name": {
"type": "string"
},
"presentation_roles": {
"items": {
"type": "string"
},
"type": "array"
},
"prior_value": {
"anyOf": [
{},
{
"type": "null"
}
]
},
"scale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"scope_bridge_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
},
"scope_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"scope_warning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"semantic_family": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"semantic_relation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"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"
},
"tag": {
"type": "string"
},
"unmatched_query_modifiers": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
}
},
"required": [
"metric_name",
"tag",
"has_value",
"match_score"
],
"type": "object"
},
"type": "array"
},
"quarter": {
"type": "integer"
},
"query": {
"type": "string"
},
"query_intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"required_query_modifiers": {
"items": {
"type": "string"
},
"type": "array"
},
"scope_bridges": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
]
},
"scope_warnings": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
]
},
"source": {
"additionalProperties": true,
"type": "object"
},
"status": {
"const": "success",
"type": "string"
},
"ticker": {
"type": "string"
},
"total_matches": {
"type": "integer"
},
"year": {
"type": "integer"
}
},
"required": [
"status",
"ticker",
"year",
"quarter",
"full_year_mode",
"query",
"total_matches",
"low_confidence",
"hint"
],
"type": "object"
}