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 — inspect it with secedgar_dataframe_describe, then analyze it with 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. SEC publishes frames for us-gaap and dei tags only, and taxonomy picks which of the two a raw tag is read from (dei for cover-page tags such as EntityCommonStockSharesOutstanding); a friendly name keeps its own mapped taxonomy. There are no ifrs-full frames, so IFRS (20-F) filers are absent from every frame; read them per company with secedgar_get_financials or secedgar_compare_companies under taxonomy ifrs-full.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"concept": "<concept>",
"period": "<period>"
},
"name": "secedgar_fetch_frames"
}
}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. Capped at 100: a larger value, up to 1000, returns what 100 returns. | |
| 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 and spellings as secedgar_get_financials (e.g., "revenue", "assets", "eps_basic", "capital_expenditures") or raw XBRL tag. | |
| taxonomy | No | Frames namespace a raw XBRL tag is read from: us-gaap for financial-statement tags, dei for cover-page entity tags such as EntityCommonStockSharesOutstanding. SEC publishes frames for no other taxonomy. A friendly name keeps its own mapped taxonomy (shares_outstanding reads dei) unless dei is passed, which reads its tags from dei instead — the same rule as secedgar_get_financials. | us-gaap |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit cap applied. | |
| data | No | Ranked companies for this metric. | |
| unit | No | Unit of measure, in 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. | |
| period | No | Calendar period the data was fetched for, echoed from input. | |
| caveats | No | Completeness warnings, else empty: fiscal-Q4 filers missing from quarterly frames (CY####Q#), proxy pay-versus-performance NetIncomeLoss rows in annual frames, 10-Q trailing-twelve-month figures in an annual frame through April of the next year, split or scale artifacts in top rows. | |
| concept | No | XBRL tag queried, after resolving any friendly name. | |
| dataset | No | Dataframe of the full frame, every reporter. Absent when canvas is unavailable or staging failed. | |
| taxonomy | No | Frames namespace the tag was read from (us-gaap or dei); a friendly name mapped to dei reads dei. | |
| truncated | No | True when the inline data[] was capped by limit. | |
| next_offset | No | Offset for the next page down the ranking. Absent on the last page. | |
| related_tags | No | Alternate-definition tags many filers use as their primary line (e.g., cash including restricted cash), whose filers are absent from data: fetch each separately, never blindly UNION. Empty when none is known. | |
| unqueried_tags | No | Same-meaning mapped tags not queried (e.g., SalesRevenueNet for revenue), whose filers are absent from data: fetch each and UNION/COALESCE in SQL. Empty for raw tags and single-tag concepts. | |
| total_companies | No | Total companies reporting this metric for this period. | |
| period_end_range | No | Range of period_end dates; filers report on their own fiscal years, so "CY2023" can span 2023-01-31 to 2024-12-31, mixing fiscal periods. | |
| value_distribution | No | Distribution across the full frame; max_to_p95_ratio is the outlier signal. |