Compare one XBRL concept across all companies
edgar_get_concept_across_companiesGet one XBRL concept for a calendar period across every SEC filer that reported it to screen and compare peers by value; supports sorting, filtering, and paging.
Instructions
Cross-company query: get one XBRL concept (e.g. Revenues, Assets, NetIncomeLoss) for one calendar period for every SEC filer that reported it, using the SEC frames API. Sortable and paged. Use for screening and peer comparison ("largest companies by total assets at end of 2023", "net income of all filers in CY2023"). For one company's history use edgar_get_company_facts. Period format: "CY2023" (annual duration), "CY2023Q2" (quarterly duration), "CY2023Q4I" (instant, for balance-sheet items like Assets). Unit e.g. "USD", "USD-per-shares", "shares", "pure". Behavior: free, read-only GET to data.sec.gov (no token). Returns paged {count,total,offset,hasMore,nextOffset,meta:{taxonomy,concept,label,unit,period,source_url},items:[{rank,cik,entity_name,value,start,end,location,accession_number}]}. Optional ciks filter restricts to given companies. Errors: NOT_FOUND (no such concept/unit/period frame), SEC_FETCH_FAILED. WHEN NOT TO USE: for one company's time series use edgar_get_company_facts; for filings use edgar_list_filings. COST: free - direct sec.gov requests from this MCP server, no APIFY_TOKEN, no Apify billing. PARAMETERS: period must match the concept type: flow items (Revenues, NetIncomeLoss) use durations "CY2023" or "CY2023Q2"; balance-sheet items (Assets, Liabilities, StockholdersEquity) need an instant such as "CY2023Q4I" - the wrong kind returns NOT_FOUND. Calendar periods are SEC-aligned approximations of each filer's fiscal period. concept, unit and taxonomy are case-sensitive path parts of one SEC frame, so all three must exist together: EPS uses unit "USD-per-shares", share counts "shares", ratios "pure"; dei concepts (e.g. EntityCommonStockSharesOutstanding) need taxonomy "dei". companies filters the frame after download (any ticker/CIK/name; unresolvable entries are silently skipped); rank is computed after that filter and the chosen sort, so rank 1 = largest value among the kept companies with value_desc. limit/offset then page the ranked rows. EXAMPLE: {"concept":"Assets","period":"CY2023Q4I","limit":10} -> top 10 filers by total assets at end of 2023.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Optional, one of "value_desc" | "value_asc" | "name", default "value_desc" (largest first); "name" = entity name A-Z | value_desc |
| unit | No | Optional, default "USD". Case-sensitive unit of measure: "USD", "USD-per-shares" (EPS), "shares", "pure" (ratios), or another currency code such as "EUR" | USD |
| limit | No | Optional page size: items to return, integer 1-500 (default 25). Example: 10 | |
| offset | No | Optional zero-based number of items to skip, integer >= 0 (default 0); pass nextOffset from the previous response, e.g. 20 | |
| period | Yes | Required. Calendar frame, pattern ^CY\d{4}(Q[1-4]I?)?$: "CY2023" = annual duration, "CY2023Q2" = quarterly duration, "CY2023Q4I" = instant at quarter end (balance-sheet items) | |
| concept | Yes | Required. Exact XBRL concept name, case-sensitive, e.g. "Assets", "Revenues", "NetIncomeLoss" | |
| taxonomy | No | Optional, default "us-gaap". One of "us-gaap", "ifrs-full", "dei", "srt" | us-gaap |
| companies | No | Optional, default omitted = all filers. 1-50 tickers, CIKs or name fragments to keep. Example: ["AAPL","MSFT","GOOGL"] |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Tool-specific context (company, source_url, ...) | |
| count | Yes | Number of items in this page | |
| items | Yes | Result rows for this page | |
| total | Yes | Total items matching the filters (before paging) | |
| offset | Yes | Offset of the first item in this page | |
| hasMore | Yes | True if more items exist after this page | |
| nextOffset | Yes | Offset to pass for the next page, or null |