Metric

Return one discovered metric or XBRL tag with current, prior, and YoY values.

Tier: public | Cache: cache-only | Playground: anonymous playground | 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/metric" \
  -H "Authorization: Bearer $EDGAR_API_KEY" \
  --data-urlencode "ticker=AAPL" \
  --data-urlencode "year=2025" \
  --data-urlencode "quarter=4" \
  --data-urlencode "metric_name=Revenue"


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,
  "metric_name": "Revenue"
}
 
response = requests.get(f"{base_url}/api/metric", 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.
`matches`	`array<object>`	Candidate fact matches; inspect labels, units, periods, and source references.

Response Fields To Inspect

status / semantic_status for whether the tool produced a usable fact set.
coverage_status and coverage_warning before treating the value as complete.
source_ref, concept names, units, and period metadata for citation and auditability.

Errors And Coverage

401 or 403: 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 403 cache 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.

Search Metrics, List Metrics, Metric Series

Generated Reference

Contract

Field	Value
Tool	`get_metric`
Method	`GET`
Path	`/api/metric`
Contract version	`1.0.0`
Schema fingerprint	`sha256:0350ec893a5d3a2a2510dc059711a93f6ec9665a0e068b32d8c4b2d8cb8accd8`

Parameters

Name	Location	Required	Type
`ticker`	query	yes	`string`
`year`	query	yes	`integer`
`quarter`	query	yes	`integer`
`metric_name`	query	yes	`string`
`full_year_mode`	query	no	`boolean`
`source`	query	no	`string`
`date_type`	query	no	`string \| null`
`role`	query	no	`string \| null`

Response Schema (200)


{
  "additionalProperties": true,
  "properties": {
    "coverage_status": {
      "anyOf": [
        {
          "enum": [
            "complete",
            "partial",
            "narrow",
            "none"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage_warning": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "matches": {
      "items": {
        "additionalProperties": true,
        "properties": {
          "axis_key": {
            "default": "__NONE__",
            "type": "string"
          },
          "current_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "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"
              }
            ]
          },
          "metric": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "presentation_roles": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "prior_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "scale": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "source_ref": {
            "anyOf": [
              {
                "additionalProperties": true,
                "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"
          },
          "yoy_change": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "yoy_change_pct": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "semantic_status": {
      "anyOf": [
        {
          "enum": [
            "ok",
            "partial",
            "empty",
            "error"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "const": "success",
      "type": "string"
    }
  },
  "required": [
    "status"
  ],
  "type": "object"
}