/api/v1/scrapping/xbrlConvert XBRL to JSON.
Convert XBRL to JSON. Pass either the XBRL document URL OR the accession number — accession is auto-extracted from the URL if only the URL is provided.
25 tokensSince v1.0.0
Why use this
Parses a single SEC XBRL filing's instance document into a clean array of fact rows: `concept`, `value`, `unit`, `period_start`, `period_end`, `dimensions`. Use this when you need the AS-FILED facts for a specific accession (e.g. to reconcile a 10-K's reported revenue against your downstream model, or to extract a custom company-specific concept like `aapl:iPhone`). For cross-company standardized financial-statement queries — where you want apples-to-apples Revenue/NetIncome across 7,000+ filers — use `GET /api/v1/financials/metrics` instead, which standardizes the messy as-filed facts into a clean canonical schema. Either input is sufficient: pass the direct XBRL document URL, or pass just the accession number and we auto-resolve the document.
Common use case
Extracting financial statements (Balance Sheet, Income Statement) in a structured format.
Returns parsed XBRL facts for a specific filing — concept, value, unit, period, dimensions. Use this when you need the as-filed facts from a single accession; for cross-company aggregates use GET /api/v1/financials/metrics (which standardizes across filings). The 25-token cost reflects the per-call XBRL parse.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| xbrl_url | query | optional | — | — | Direct URL of the XBRL instance document on SEC EDGAR (the `.xml` or inline-XBRL `.htm` file containing tagged facts — NOT the filing index page). Server-side rejected if not on `sec.gov`. At least one of `xbrl_url` or `accession_number` is required; if both are passed, `xbrl_url` takes precedence. | https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm |
| accession_number | query | optional | — | — | SEC accession number with or without dashes (e.g. `0000320193-24-000123` or `000032019324000123` both work). When passed alone, the server auto-resolves the primary XBRL instance document by fetching the filing's index page. At least one of `xbrl_url` or `accession_number` is required. | 0000320193-24-000123 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| accession_number | string | no | SEC accession number of the source filing in canonical `XXXXXXXXXX-YY-NNNNNN` format (always normalized to dashed form regardless of input). |
| form_type | string | no | Source filing's form type as detected from the XBRL instance metadata (typically `10-K`, `10-Q`, `8-K`, `20-F`, `40-F`). Useful for cost-budgeting downstream processing (10-Ks have 800-2000 facts; 8-Ks typically have 5-50). |
| period_end | string | no | ISO `YYYY-MM-DD` reporting period end of the filing's primary context (the fiscal-quarter or fiscal-year end). For 10-K/10-Q this is the canonical period the financials cover; for 8-K it's the event date. |
| facts | array | no | Array of XBRL fact rows. One row per `(concept, period, dimensions)` tuple — same concept can appear multiple times if reported across multiple periods or dimensional members (e.g. revenue by geographic segment). Empty array for filings that have no XBRL (rare; typically only NT amendments and some pre-2010 archival filings). |
| facts[].concept | string | no | Concept name in `prefix:LocalName` format. Standard concepts use the `us-gaap:` prefix (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`, `us-gaap:Assets`); company-specific extensions use the company's own prefix (e.g. `aapl:iPhone`, `tsla:VehicleSales`). Pass to `GET /api/v1/facts/by-concept` for cross-company aggregations of the same concept. |
| facts[].value | number | yes | Numeric fact value in the unit specified by `facts[].unit`. Null for textual or non-numeric facts (e.g. company description, accounting policy strings). NOT scale-adjusted — values are reported as-filed; reconcile against `unit` to interpret (e.g. value=391035 + unit=USD-thousands means $391.035M). |
| facts[].unit | string | yes | XBRL unit reference. Common values: `USD` (US dollars at 1:1 scale), `shares` (raw share count), `pure` (dimensionless ratios — typically `0-1`), `USD-per-share` (per-share dollar values), `iso4217:JPY`/`iso4217:EUR` (foreign currencies). Null only when `value` is null (textual facts). Always check unit before arithmetic — companies routinely mix `USD` and `USD-thousands` within the same filing. |
| facts[].period_start | string | yes | ISO `YYYY-MM-DD` start date for duration concepts (income-statement and cash-flow facts that cover a period). Null for instant concepts (balance-sheet facts that are point-in-time at `period_end`). Use the `period_start` + `period_end` pair to detect Q vs YTD vs TTM scope. |
| facts[].period_end | string | no | ISO `YYYY-MM-DD` end date for the fact. For instant concepts this is the as-of date; for duration concepts this is the period end. Always present. |
| facts[].dimensions | object | yes | XBRL dimensional context as a `{axis: member}` map (e.g. `{StatementBusinessSegmentsAxis: 'IPhoneSegmentMember'}`). Null when the fact has no dimensional qualifier (the most common case — un-dimensioned facts represent the consolidated entity). Use to filter segment-level vs total-level facts (`facts.filter(f => f.dimensions === null)` returns the consolidated view). |
Sample response
·
- "accession_number": "0000320193-25-000123"
- "form_type": "10-K"
- "period_end": "2025-09-28"
- "facts":
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/scrapping/xbrl?api_Token=YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).