Skip to main content
Tutorial

SEC XBRL API: Company Financials as JSON for Agents

Get any reported XBRL concept, such as revenue, for one company or for every filer in a period, through SEC companyconcept and frames with one API key.

fastcrw
By RecepNovember 15, 20266 min read

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

CapabilityAnswersOptionsREST size seen on 2026-11-05
companyconceptOne us-gaap tag for one company, full historycik, concept19.5 KB (Apple, revenue)
companyfactsEvery tag one company has reportedcik3.9 MB (Apple)
framesOne tag for every filer in one periodconcept, period74 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 accn and filed.
  • frames holds 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

Try SEC EDGAR on Pergamon

FAQ

Frequently asked questions

Which SEC XBRL endpoint should I call first?
Call companyconcept when you know the us-gaap tag and want one company's history. Call frames when you want every filer's value for one period. Use companyfacts only when you need every tag one company reported, and expect a large response.
Why does my SEC CIK return a 404?
The data.sec.gov paths need the 10-digit, zero-padded CIK. Apple is cik=0000320193, not cik=320193. The unpadded form returns a 404 upstream_error from SEC EDGAR.
Does the API tell me whether a company is a good investment?
No. It returns values from SEC filings with the accession number and filing date, so you can check the source yourself. It does not rate, rank for investment or recommend any company.

Get Started

Try fastCRW free

Run a live request in the playground — no signup required. Or grab a free API key with 500 credits, earn up to 500 more, no credit card.

Continue exploring

More tutorial posts

View category archive