Skip to Content
Tool ReferenceXBRL FactsConcept

Concept

Resolve one registry-backed financial concept from cached filing facts.

Tier: public | Cache: cache-only | 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/concept" \
  -H "Authorization: Bearer $EDGAR_API_KEY" \
  --data-urlencode "ticker=AAPL" \
  --data-urlencode "year=2025" \
  --data-urlencode "quarter=4" \
  --data-urlencode "concept_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,
  "concept_name": "revenue"
}
 
response = requests.get(f"{base_url}/api/concept", headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

Key Response Fields

FieldTypeWhy It Matters
statusconst "success"Transport-level success indicator inside the JSON response.
semantic_status"ok" | "partial" | "empty" | "error" | nullWhether the response is semantically usable, partial, empty, or errored.
coverage_status"complete" | "partial" | "narrow" | "none" | nullCompleteness signal; do not present partial or narrow coverage as complete.
coverage_warningstring | nullHuman-readable explanation of missing or ambiguous coverage.
availablebooleanFinancial fact or concept field; inspect unit, period, and source context before using it.
conceptobjectFinancial fact or concept field; inspect unit, period, and source context before using it.
concept_definition_versionintegerFinancial fact or concept field; inspect unit, period, and source context before using it.
concept_namestringFinancial fact or concept field; inspect unit, period, and source context before using it.

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.
  • This tool is cache-only; if the target filing is not warm, warm it through an allowed paid path before retrying.
  • Treat partial coverage, empty arrays, and warning fields as answer-quality signals even when HTTP status is 200.

Statement, Compare Concept, Concept Trend

Generated Reference

Contract

FieldValue
Toolget_concept
MethodGET
Path/api/concept
Contract version1.0.0
Schema fingerprintsha256:fc15f8832aaffcf3388ebaf199b1381aede48afe0fec89fefab311ea742793ac

Parameters

NameLocationRequiredTypeNotes
tickerqueryyesstring
yearqueryyesinteger
quarterqueryyesinteger
concept_namequeryyesstring
full_year_modequerynoboolean
sourcequerynostring
date_typequerynostring | null

Response Schema (200)

{
  "additionalProperties": true,
  "properties": {
    "available": {
      "type": "boolean"
    },
    "concept": {
      "additionalProperties": true,
      "type": "object"
    },
    "concept_definition_version": {
      "type": "integer"
    },
    "concept_name": {
      "type": "string"
    },
    "concept_registry_version": {
      "type": "integer"
    },
    "coverage_status": {
      "anyOf": [
        {
          "enum": [
            "complete",
            "partial",
            "narrow",
            "none"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage_warning": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "dimensions_considered": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ]
    },
    "equivalents_considered": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "semantic_status": {
      "anyOf": [
        {
          "enum": [
            "ok",
            "partial",
            "empty",
            "error"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "const": "success",
      "type": "string"
    }
  },
  "required": [
    "status",
    "available",
    "concept_name",
    "concept_registry_version",
    "concept_definition_version",
    "concept",
    "equivalents_considered"
  ],
  "type": "object"
}
Concept TrendFinancials