Secedgar Fetch Frames
secedgar_fetch_framesFetch SEC XBRL frames for one concept × one period across all reporting companies. Inline response returns a page of the ranked companies — start at the top or pass offset/next_offset to walk further down the ranking; the full frames response (all reporters) is materialized as df_ when a canvas is available, queryable via secedgar_dataframe_query. Accepts friendly names like "revenue" or "assets" (discover via secedgar_search_concepts) or raw XBRL tags. One call hits one XBRL tag — when a friendly name maps to multiple same-meaning tags, the response's unqueried_tags lists the others; call again per tag and UNION/COALESCE in SQL with an analysis-specific priority (e.g. SalesRevenueGoodsNet is goods-only). The response's related_tags separately flags alternate-DEFINITION tags a meaningful share of filers use as their primary line (e.g. cash incl. restricted cash, equity incl. noncontrolling interest) — a whole-universe screen on the base tag silently omits those filers; query them separately, but do not blindly union (the semantics differ). Response includes value_distribution and period_end_range to flag XBRL scale-factor anomalies and fiscal-year mixing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort direction. "desc" for highest values first (typical for revenue, assets). "asc" for lowest values. | desc |
| unit | No | Unit of measure. Use "USD-per-shares" (or equivalently "USD/shares") for EPS, "shares" for share counts, "pure" for ratios. Ignored when concept resolves to a friendly name with a known unit. | USD |
| limit | No | Number of companies to return. | |
| offset | No | Rank to start the page at, 0-based, over the sorted frame. Pass the next_offset from the previous response to read the next page — the ranked list is fetched whole and sliced, so paging is stable and gap-free. An offset at or past total_companies returns an empty page. | |
| period | Yes | Calendar period. Use duration periods (no I suffix) for income/cash-flow items: "CY2023" (full year), "CY2024Q2" (single quarter). Use instant periods (I suffix) for balance-sheet items: "CY2023Q4I" (snapshot at Q4 close). | |
| concept | Yes | Financial concept — same friendly names as secedgar_get_financials (e.g., "revenue", "assets", "eps_basic") or raw XBRL tag. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit cap applied. | |
| data | No | Ranked companies for this metric. | |
| unit | No | Unit of measure used for the lookup (always normalized to dashed form, e.g. "USD-per-shares"). | |
| error | No | Present when the call failed. Absent on success. | |
| label | No | Human-readable concept label. | |
| shown | No | Number of companies shown inline. | |
| notice | No | Guidance when the requested offset lands past the end of the ranked list. | |
| offset | No | Rank the returned page starts at, 0-based — the effective offset applied. | |
| period | No | Calendar period the data was fetched for, echoed from input. | |
| caveats | No | Data-completeness warnings specific to this query. Currently populated for duration periods 'CY####Q[1-4]', where SEC XBRL omits filers' fiscal Q4 (reported only as the 10-K residual) — affected filers are silently absent from the frame. Empty for annual ('CY####') and instant ('CY####Q#I') periods, where the underlying facts exist and the frame is complete. | |
| concept | No | XBRL tag the data was actually fetched against (after resolving any friendly name). | |
| dataset | No | Canvas dataframe handle holding the full frames response. Absent when canvas is unavailable or materialization failed. | |
| truncated | No | True when the inline data[] was capped by limit. | |
| next_offset | No | Offset to pass on the next call to continue down the ranking. Absent on the last page (no companies remain past this one). | |
| related_tags | No | Alternate-DEFINITION XBRL tags (distinct from same-meaning `unqueried_tags`) that a meaningful share of filers use as their primary line for this metric — e.g. `cash` filers reporting `CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents` (incl. restricted cash), `equity` filers reporting `StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest` (incl. noncontrolling interest). These filers are NOT in `data` or the dataframe, so a whole-universe screen on the base tag silently under-counts. To recover them, run a separate fetch_frames against the alternate tag — do NOT blindly UNION (definitions differ; you would mix or double-count). Empty when the concept has no known high-coverage alternate. | |
| unqueried_tags | No | Other same-meaning XBRL tags in the friendly-name mapping that this call did NOT query (historical/variant spellings of the same metric). Empty for raw tags or single-tag concepts — for alternate-DEFINITION tags some filers use instead, see `related_tags`. For "revenue" this typically lists `Revenues`, `SalesRevenueNet`, `SalesRevenueGoodsNet` — filers reporting under legacy variants are absent from `data`; call again per tag and UNION/COALESCE in SQL to recover them. | |
| total_companies | No | Total companies reporting this metric for this period. | |
| period_end_range | No | Range of period_end dates across the frame. SEC normalizes to calendar periods but filers report against their own fiscal year-ends, so a "CY2023" duration frame can contain period_ends from 2023-01-31 (January-FY filers like Walmart) to 2024-12-31 (calendar-FY filers reported late). Wide ranges mean cross-comparison mixes fiscal periods. | |
| value_distribution | No | Distribution stats across the full frame, computed during materialization. Use `max_to_p95_ratio` as the primary outlier signal — it catches scale-factor anomalies even when median is 0 or negative. |