By the fastCRW team · Catalogue figures checked 2026-11-05 against GET /v1/data · Verify independently before relying on any figure.
To read a company's reported financials from SEC EDGAR as JSON, call one of three XBRL endpoints. companyconcept returns one tag for one company across its filings, companyfacts returns every tag one company has reported, and frames returns one tag for every filer in one period. Pergamon exposes all three under the sec provider, behind one API key. Each response carries the SEC source line and the licence text.
Three XBRL endpoints and when to use each
| Capability | Answers | Options | REST size seen on 2026-11-05 |
|---|---|---|---|
companyconcept | One us-gaap tag for one company, full history | cik, concept | 19.5 KB (Apple, revenue) |
companyfacts | Every tag one company has reported | cik | 3.9 MB (Apple) |
frames | One tag for every filer in one period | concept, period | 74 KB (revenue, CY2025Q4) |
Start with companyconcept when you know the tag. Use frames when you want to rank or screen companies for one period. Avoid companyfacts inside an agent loop: it is large, and over MCP a result above 256 KiB is refused, not truncated.
Start from a company name
If you only have a name, secfts/entity-suggest finds the filer. The call below returned 230 matches for apple at check time, and the top hit's _source holds the entity name and ticker (Apple Inc. (AAPL)).
curl "https://api.fastcrw.com/v1/data/secfts/entity-suggest?keysTyped=apple" \
-H "Authorization: Bearer $CRW_API_KEY"
The hit's _id is the CIK without padding (320193). Pad it to ten digits before you call the XBRL endpoints, because the data.sec.gov paths reject the short form.
One concept for one company
The cik must be the 10-digit, zero-padded form. Apple's CIK is 320193, but cik=320193 returns a 404 upstream_error from SEC EDGAR, while cik=0000320193 returns 200. The concept is the bare us-gaap tag name, without the taxonomy prefix.
curl "https://api.fastcrw.com/v1/data/sec/companyconcept?cik=0000320193&concept=RevenueFromContractWithCustomerExcludingAssessedTax" \
-H "Authorization: Bearer $CRW_API_KEY"
Trimmed output from a live call (200, credits_used 1). The array is sorted oldest first, so the last entry is the newest:
{
"success": true,
"provider": "sec",
"capability": "companyconcept",
"credits_used": 1,
"provenance": {
"source": "SEC EDGAR",
"attribution_text": "Source: U.S. Securities and Exchange Commission, EDGAR"
},
"data": {
"entityName": "Apple Inc.",
"tag": "RevenueFromContractWithCustomerExcludingAssessedTax",
"units": {
"USD": [
{"start": "2025-09-28", "end": "2026-06-27", "val": 364357000000, "accn": "0000320193-26-000020", "fy": 2026, "fp": "Q3", "form": "10-Q", "filed": "2026-07-31"},
{"start": "2025-09-28", "end": "2026-09-26", "val": 478834000000, "accn": "0000320193-26-000026", "fy": 2026, "fp": "FY", "form": "10-K", "filed": "2026-11-03", "frame": "CY2026"}
]
}
}
}
How to read one entry
Each entry is one reported value. start and end give the period it covers. fy, fp and form say which fiscal year, which period (FY for the full fiscal year, Q3 for the third fiscal quarter) and which SEC form it came from. filed is the date of that filing, and accn is the accession number, so you can point to the exact document. The frame field appears only when SEC has assigned the value to a calendar frame such as CY2026.
The 10-Q row above covers nine months (2025-09-28 to 2026-06-27), not one quarter, and its fp is still Q3. Filter on start and end before you add or compare rows.
Build an annual history
A concept series mixes annual and quarterly values, and later filings repeat earlier periods. The script below keeps only full-year values from 10-K filings and prints the three most recent. It was run live against the same concept.
# pip install crw
from crw import CrwClient
client = CrwClient() # reads CRW_API_KEY
res = client.get_data("sec", "companyconcept", {
"cik": "0000320193",
"concept": "RevenueFromContractWithCustomerExcludingAssessedTax",
})
annual = [u for u in res["data"]["units"]["USD"] if u["form"] == "10-K" and u["fp"] == "FY"]
print(len(annual), "annual 10-K values")
for u in annual[-3:]:
print(u["fy"], u["end"], u["val"], u["filed"], u["accn"])
Real output:
40 annual 10-K values
2025 2025-09-27 416161000000 2025-10-31 0000320193-25-000079
2026 2025-09-27 416161000000 2026-11-03 0000320193-26-000026
2026 2026-09-26 478834000000 2026-11-03 0000320193-26-000026
The fiscal 2025 period appears twice. The fiscal 2026 10-K repeats the prior year's value under its own accession number, filed on 2026-11-03. Keep one row per end date, and decide whether you want the value as first filed (the original 10-K's filed date) or as the latest filing shows it. Keeping accn and filed makes that choice visible.
Tag aliases: an old series can stop
Companies change the XBRL tag they use over time. Apple's Revenues series still returns 200 for the same CIK, but its last entry ends on 2018-09-29 (fiscal 2018, filed 2018-11-05). The current revenue figure sits under RevenueFromContractWithCustomerExcludingAssessedTax, as in the call above. Before you trust a series, check the last end date.
curl "https://api.fastcrw.com/v1/data/sec/companyconcept?cik=0000320193&concept=Revenues" \
-H "Authorization: Bearer $CRW_API_KEY"
One concept across every filer (frames)
frames returns one value per company for the period you name. Use CY2025Q4 for a duration concept such as revenue. An instant concept such as Assets takes an I suffix, as in CY2025Q4I. The example below uses the Python SDK (crw 0.41.0) and was run live.
# pip install crw
from crw import CrwClient
client = CrwClient() # reads CRW_API_KEY
frames = client.get_data("sec", "frames", {
"concept": "RevenueFromContractWithCustomerExcludingAssessedTax",
"period": "CY2025Q4",
})
print(frames["provenance"]["attributionText"])
rows = [r for r in frames["data"]["data"] if r["val"]] # drop zero values
print(len(rows), "filers with a non-zero value")
for r in sorted(rows, key=lambda r: r["val"], reverse=True)[:3]:
print(r["entityName"], r["val"], r["end"])
Real output:
Source: U.S. Securities and Exchange Commission, EDGAR
473 filers with a non-zero value
Apple Inc. 143756000000 2025-12-27
McKESSON CORPORATION 106158000000 2025-12-31
MICROSOFT CORPORATION 81273000000 2025-12-31
Each row holds accn, cik, entityName, loc, start, end and val. The loc field is a region code such as US-CA, so you can filter a frame by state without a second call. The cik in a frame row is a number, so pad it before you pass it to companyconcept.
The filter matters: the same frame has 479 rows, and 6 of them hold a zero value. The ranking shows only the values filers reported. It is not an analysis of the companies.
From an agent (MCP)
An MCP client makes the same call with crw_get_data. The hosted endpoint returned this companyconcept result with creditsUsed 1. MCP results use camelCase keys, so attributionText appears under provenance and there are no cache fields.
{"name": "crw_get_data", "arguments": {"provider": "sec", "capability": "companyconcept", "options": {"cik": "0000320193", "concept": "RevenueFromContractWithCustomerExcludingAssessedTax"}}}
The same hosted endpoint refused companyfacts for Apple with [result_too_large] ("The result is 3767 KiB, over the 256 KiB limit"). Narrow the request to one concept with companyconcept instead. A refused call on a server source is refunded.
Limits
- SEC's fair access rules still apply upstream. SEC's own page gives a current maximum of 10 requests per second (SEC, accessing EDGAR data).
- The values are what filers reported. A later filing can restate an earlier period, and it shows up as another entry with its own
accnandfiled. framesholds one value per company. A company that reports the concept under a different tag does not appear in that frame.- This is not investment advice. The API returns filed data and does not rate or recommend any company.
Sources
Related: Public data API for AI agents · SEC EDGAR API in Python · Build a finance research agent · Pergamon catalogue
