Most guides to the sec filings api say the same thing: call the company facts endpoint, take the newest value for each XBRL tag, load it into your warehouse, done. That advice gets a demo running in an afternoon. It also produces a database that misstates a company the first time an amendment lands.

A tag is not a number. us-gaap:Revenues can hold a dollar total in one fact and a per-share figure in another. The same tag reappears inside segment dimensions, so the consolidated total and the North America slice carry the same name. And when a company files an amended 10-K, the corrected figure arrives under a new accession number while the original stays in the archive, unchanged and still machine-readable.

Treat accession number, period and unit as the record key, and the confusion dissolves. The submissions feed becomes a fast notification that a filing exists. A fact becomes a number tied to one filing, one period and one unit. Everything below follows from that split: which endpoint to call, which fields to keep, how far back the archive reaches, how to stay inside the access rules, and when a raw EDGAR pipeline stops being the right tool for the job.

Table of Contents

Official SEC Filings API Endpoints

The public SEC filings API is open JSON served from data.sec.gov. No API key, no account, no keyed search product to license. You send a GET request with a URL that names a company by its zero-padded CIK, and the response is a JSON document any standard library can parse.

Dataset Path pattern Returns Typical freshness
Submissions data.sec.gov/submissions/CIK##########.json Current filing history for one filer Updated as submissions disseminate
Company Facts data.sec.gov/api/xbrl/companyfacts/CIK##########.json All XBRL concepts for one company Refreshed throughout the day
Company Concept data.sec.gov/api/xbrl/companyconcept/CIK##########/{taxonomy}/{tag}.json One tag across that company's periods Refreshed throughout the day
Frames data.sec.gov/api/xbrl/frames/{taxonomy}/{tag}/{unit}/{frame}.json One tag across companies for a period Refreshed throughout the day
Bulk extract companyfacts.zip Company-facts and frame data in bulk Published as bulk files for backfill

The two calls a first integration makes

Start with two documents and ignore the rest until you need them. Submissions tells you which filings exist for one filer, with accession numbers and primary document names. Company Facts returns every available XBRL concept for that company in a single payload, which is why it is often the first endpoint developers wire up and the one that causes the most damage when a latest-value shortcut flattens amendments, units and periods.

The SEC frames these as two foundational datasets, filer submission histories and structured XBRL financial-statement data, and says the JSON structures update throughout the day as submissions are disseminated. It lists 10-K, 10-Q, 8-K, 20-F, 40-F and 6-K among the supported filing families, together with their variants, in the EDGAR application programming interfaces documentation.

Why the other three paths exist

Company Concept narrows the payload to one taxonomy and one tag for one company. Reach for it when a chart needs a single line item across many periods and you do not want to parse the full facts document. Frames flips the axis: one concept, one unit, one calendar period, many companies. That is the shape a screen or ranking job wants, because it removes the per-company loop entirely.

Bulk is the escape hatch. The zip bundles company-facts data and frame data, so a corpus backfill costs one download instead of thousands of calls. Treat it as infrastructure for catch-up work, while the live feed stays on submissions.

Two operational habits belong in the client from day one. Respect the fair-access ceiling of 10 requests per second and cache by accession number, period and unit so identical histories are not re-pulled on a timer. When your own service later fronts these feeds, capacity becomes ordinary API engineering rather than an EDGAR question; the vocabulary of queueing, concurrency and warm-up appears in material on scaling AI model-serving endpoints.

Read the return shape before writing a client class. Two paths answer which filings exist and where their packages live. Three paths answer which number was reported, for which period, in which unit.

Four Data Categories Inside EDGAR

EDGAR holds four kinds of thing, and nearly every integration bug comes from asking one of them to do another's job: discovery, documents, facts and bulk.

A diagram illustrating the four main data categories within the SEC EDGAR archive: Discovery, Documents, Financial Data, and Ownership.

The diagram above sorts the archive by what each branch holds. Insider and ownership filings (Forms 3, 4 and 5) arrive through the same two paths as everything else, so they need no separate plumbing: a Form 4 is a discovery record plus a document.

Discovery answers existence, nothing more

The submissions history gives you form type, filing date, accession number, primary document name and the related files list. That is enough to answer "did this company file a 10-Q for the June quarter, and what's its accession number". It is not enough to answer "what was revenue". The endpoint knows a filing happened; it doesn't know what the filing says.

Documents are the package, not the number

An accession number such as 0000320193-24-000123 becomes a directory once you remove the dashes, and the primary document filename from the submissions record completes the URL on www.sec.gov. That path gets you the cover page, the financial statements, the exhibits and the footnotes. It also gets you the prose that XBRL never tags: the lease commitments table, the revenue disaggregation paragraph, the sentence explaining why a segment was reorganized.

Facts are the structured numbers

A fact carries a taxonomy, a tag, a unit, a period, a fiscal year and period, a form, a filed date, an accession number and sometimes a frame. It can do cross-company comparison for a period. It cannot tell you why the number moved, and it cannot hand you a figure the company chose to disclose only in narrative form.

Bulk exists for corpora, not for ticks

The zip is the right tool when a research job needs every company rather than one ticker, and the wrong tool for anything that needs to reflect today's filing. Its job is backfill; its failure mode is a pipeline that treats a downloaded archive as current.

A single filing often needs more than one category. An 8-K is a discovery and document problem, because the item codes tell you a rule was triggered and the item text tells you what happened. A debt balance is a facts problem. A footnote about variable interest entities is a document problem that no tag will solve. Identify which category your question belongs to before you pick an endpoint, and half the design decisions make themselves.

Archive Coverage by Era

Imagine a research desk building a twenty-year revenue history for a manufacturer listed in the 1980s. Someone assumes the API will return figures from the start of that listing and plans the chart accordingly. The first pull returns nothing before the mid-1990s, and the whole scope has to be renegotiated. Knowing the coverage boundary in advance saves that conversation.

A timeline chart titled Archive Coverage by Era illustrating the evolution of SEC electronic filing milestones.

The milestones run in a straight line. The Commission began developing EDGAR in 1983, opened a pilot system to volunteer filers in fall 1984, and began mandating electronic filing in early 1993, replacing a paper-based disclosure process with machine-readable submissions. Internet-based filing, HTML documents with graphics and expanded hyperlinks went live in EDGAR on 30 May 2000, following amendments adopted on 24 April 2000. Diskettes stopped being available on 10 July 2000, and the Financial Data Schedule requirement ended on 1 January 2001. The SEC's own EDGAR overview records all of it and states the number that matters most for planning: public index files cover all public filings from 1994Q3 onward.

That date is the practical floor, not 1983. A historical screen can reach the third quarter of 1994 for filing metadata and documents. It cannot reach a clean electronic set from the 1980s, because electronic filing wasn't mandatory yet and the paper trail wasn't machine-readable.

The split that surprises people is internal to the archive. Filing metadata and document images extend back through the whole electronic era. XBRL facts are a later layer, tagged only as companies adopted structured reporting, and they're sparse or entirely absent on older filings. Company Facts will not rebuild a 1990s income statement, no matter how you query it.

Design the backfill around that asymmetry. Walk index files and submissions first, write the filing rows you have, and store nulls where no tagged fact exists rather than interpolating a plausible number.

A null in a fact column is honest. An estimate that fills the gap is not, and it will survive every downstream test because it looks like the rest of the data.

Here's a walkthrough of how the filings feed behaves in practice, including the lag between a filing landing and its facts appearing.

Fields to Keep from Each Payload

Two JSON shapes matter, and a parser has to persist different things from each. The submissions document is a set of arrays describing filings. The company facts document is a tree: taxonomy, then tag, then unit, then an array of fact objects. Miss either structure and you'll spend a quarter patching.

Payload Field Keep it because
Submissions cik Zero-padded 10-digit filer key used on every other endpoint
Submissions accessionNumber Stable filing id that resolves the document directory
Submissions form Form family, including amendments that supersede an earlier file
Submissions filingDate Dissemination date, distinct from the period end
Submissions primaryDocument Filename that completes the filing URL
Company facts taxonomy and tag Names the concept, such as us-gaap and Revenues
Company facts units Separates USD from shares and per-share series
Company facts fy, fp, end Fiscal year, fiscal period and period end
Company facts form, filed, accn Ties the number back to the filing that reported it
Company facts frame Optional calendar frame for cross-company comparison

The submissions side

Keep cik, the entity name, and the recent filings arrays: accessionNumber, form, filingDate, reportDate, primaryDocument and primaryDocDescription. One trap sits here. Older history may be stored in a referenced file rather than inlined in the recent block, so an empty recent window doesn't mean the company had no filings. Follow the reference before you conclude anything about a dormant issuer.

The facts side

A fact object carries val plus end or start, then fy, fp, form, filed, accn and optionally a frame such as CY2024Q1I. The nesting matters more than the fields. USD, USD/shares and pure are separate series of the same tag, and a parser that grabs the first unit key mixes dollars with per-share figures. Dimensional context is the second trap: a total and a segment share a tag but not a meaning.

Working rule: every number your schema stores carries the accession that produced it, the unit it was reported in, and the period it covers. If any of the three is missing, the row isn't a fact yet.

One revenue figure, selected properly

Take a large-cap issuer and a 10-Q you just discovered in the submissions feed. The revenue you want is the us-gaap fact whose accn matches that accession, whose unit is USD, and whose end matches the period the filing covers. Not the entry with the largest end in the array, and not the last one appended. If two revenue tags both exist in that filing, pick the one the filing uses for the primary statement line, and keep the tag name with the value.

Amendments make this concrete. A 10-K/A shares concepts with the original, carries its own accession, and can supersede the earlier figures. Sort by value or by date and you lose; join on accession and period and you keep both versions, with a flag marking which one supersedes.

The data quality engineering practices that keep warehouse tables trustworthy apply here with one addition: validate that every stored fact resolves to a filing you have already ingested. An orphan number is worse than a missing one. Teams building a stock screener API hit this early, because a screener queries thousands of tag and period combinations, and one mis-keyed join turns into a wrong ranking rather than a wrong cell.

Fair Access Caching and Bulk Pulls

EDGAR may be free to query, but its request budget is finite. The SEC's EDGAR APIs documentation sets a ceiling of 10 requests per second for each user or application, requires a declared User-Agent identifying the application and a contact email, and warns that access can be limited to preserve service availability. Because there is no API key to expire and no invoice to audit, an undisciplined pipeline can run past that budget until responses start failing.

The arithmetic explains why caching matters. A nightly company-facts sweep across 5,000 CIKs needs 5,000 requests. At the 10-request ceiling, that is just over eight minutes of uninterrupted traffic before the job downloads a single filing document. A laptop test may look harmless. Add a development environment, an impatient retry loop, and a second scheduled job, and the pipeline starts to resemble the traffic pattern fair access is meant to control.

Design the client around that budget:

  • Identify the client. Use a descriptive User-Agent with an application name and a reachable contact. Anonymous traffic gives an operator little reason to distinguish a broken script from abusive automation.
  • Cache raw payloads by CIK and validator. Store submissions and company-facts responses with an ETag or content hash. A conditional request returning 304 Not Modified confirms freshness without paying for another response body.
  • Key derived rows by accession, period and unit. The cached payload tells you which filing exists; the stored fact identifies which filing, reporting period and measurement unit produced the value. That separation prevents an amended accession from overwriting the original.
  • Throttle through a token bucket. Keep the steady rate below the published ceiling and back off exponentially on 403 or 429. Immediate retries convert a temporary warning into sustained pressure.
  • Split discovery from extraction. Poll submissions only for tracked CIKs. When a new accession appears, let a separate job refresh the affected documents and facts.
  • Use bulk archives for backfill. A research-scale history belongs in a bulk download, not in thousands of per-company requests.

Practical rule: if a job re-downloads a filing history it already holds, that job is a caching bug with a scheduler attached.

Treat the ceiling as a steady-state budget rather than a startup burst. Gradual ramp-up, conditional requests and accession-aware storage keep EDGAR responsive and keep your fact table tied to the filings that produced it.

How to Ingest One Company

A flow chart illustrating the four-step process for ingesting company data using the SEC filings API.

Production ingestion is a sequence, and each step exists to prevent a specific failure. Work through it once for a single CIK before you generalize anything.

  1. Resolve the ticker to a CIK and pad it. The submissions path takes a zero-padded ten-digit CIK, so a seven-digit value with leading zeros dropped returns nothing useful. Store the padded form as the primary key.
  2. GET the submissions document. Send a descriptive User-Agent with a contact, and keep your request rate inside the budget. This one call replaces a crawl of the filing index for most use cases.
  3. Read the filing history, including older files. Take filings.recent and follow any referenced historical file. Then filter to the form families you store, so a client doesn't choke on dozens of immaterial form types.
  4. Resolve each new accession to its documents. Build the Archives directory, fetch only the primary document and the specific exhibits you need, and keep the accession on every stored document row.
  5. Refresh company facts on a separate schedule. Pull the facts document once per CIK, then select the facts whose accn matches the accession you just accepted. The submissions feed told you a filing exists; the facts document carries the numbers.
  6. Persist with full context. Write accession, form, filed date, fiscal year, fiscal period, unit, dimensions and value. Accession, period and unit together are the record key, because the same XBRL tag is not one number. When an amended form arrives, mark it as superseding the prior accession for that period instead of overwriting history.
  7. Cache and poll. Keep the cached submissions document for the low-latency trigger, and refresh facts afterwards rather than on every tick. The SEC updates filing metadata and XBRL data at different speeds, so a two-stage job matches the source instead of fighting it.

The EDGAR API reference describes the split directly: submissions and extracted XBRL facts are separate data sets under data.sec.gov, they update on different cadences, and older submissions records can live in referenced historical files. What it will not do is choose your facts. That selection rule belongs to your pipeline, and the safe version is strict: match a fact to the accession and period that produced it, keep its unit and dimensional context, and never let a later accession replace an earlier one. The same economic concept can appear in several units or contexts, and an amendment supersedes the submission it corrects.

The failure mode step 5 exists for is quiet. A later filing can be an 8-K that announces a financing and never touches the annual revenue fact, so "most recent filing wins" corrupts the series while looking perfectly current. Matching on accession keeps the 8-K's own facts separate from the 10-K's.

Build the smallest happy path first: one CIK, one 10-Q, one accession, one revenue fact in USD. Then add the amendment branch. Then the backfill. Automating the sequence across a whole universe before that works end to end is how teams end up with a scheduler nobody trusts, which is the problem a Kagool pipeline automation strategy addresses at the orchestration layer. If you're exposing filing-sourced figures through your own product, the same reliability habits discussed in this fintech API guide apply to the surface you publish.

Crosswalk from Ticker to Fact

A ticker is a label on a listing. The CIK is the identity the archive uses, and the two don't map one-to-one. Almost every "the API returns the wrong company" report traces back to this hop.

Start with the SEC's ticker-to-CIK list. Look the symbol up there, not in a market data vendor's reference file, and left-pad the result to ten digits before it touches a URL. A symbol that isn't in the list isn't an SEC filer, whatever else it might be.

Two edge cases break naive joins. A single CIK can carry several tickers across share classes, so a lookup keyed on ticker returns the same filer twice under different symbols. And a symbol reused after a corporate action points at a different CIK than a casual search suggests, which is why the ticker alone is never a safe join key across time.

From CIK, submissions yields accession numbers. Strip the dashes from an accession and you get the Archives directory path; append the primaryDocument filename and you have the filing itself. That's the discovery-to-document route, and it works for every form family.

The critical join is accession to fact. Company Facts links back through accn, and that's the only safe link. Filing date and period end are different dates, so joining on filingDate alone misaligns a 10-Q filed in November against a September quarter. An amendment carries its own accession, so a join on period end returns two candidate rows with no way to tell which one the company stands behind.

Frames introduce a fourth key. The frame string lines up a calendar period across companies, which makes rankings easy, but it only includes facts tagged into that frame. A company that reports off-calendar or uses a different tag for the same concept drops out of the result set, which looks like missing data rather than a filter.

Follow one identifier hop at a time. Ticker to CIK, CIK to accession, accession to fact, frame only when the question is cross-sectional.

Foreign private issuers change the form families, not the mechanics. They often appear as 20-F annual reports or 6-K interim disclosures rather than 10-K and 10-Q, and Canadian issuers may file 40-F. Your form filter needs those from the start if the universe is global.

Scope matters too. Statutory accounts filed with UK Companies House, and equivalents in other jurisdictions, are outside this API entirely. No amount of endpoint exploration will surface them, because EDGAR doesn't hold them.

A three-line example makes the path concrete. Take a symbol, look it up in the ticker file, and pad the CIK to ten digits. Take that CIK into submissions and pick the latest 10-Q accession. Take that accession into company facts and select the USD revenue fact whose accn matches, then store it with its period, unit and filing date.

Choose Raw EDGAR or an Extracted Feed

There's a real decision at the end of this, and it isn't about which option is more modern.

Stay on data.sec.gov when you need the official archive, filing discovery, document text, or a fact you can tie directly to an accession and a unit. That path gives you provenance for free, because every number you store points at a public record. The price is ownership: CIK padding, caching, amendment handling, unit discipline, and a null wherever XBRL never tagged a figure. For a team with one or two engineers and a narrow universe, that's affordable.

Move to an extracted feed when the figure you need sits in a footnote that the standard tags don't isolate cleanly. Interest-bearing debt assembled from the debt note and the lease note is the classic case. So is a revenue split by source, or an operating lease obligation disclosed in prose with a table. The raw tags exist for some of it and miss the rest, and the gap is exactly where a screening product needs numbers.

Geography makes the same argument. Once a workflow spans SEC filers, UK Companies House accounts and Canadian filings, you're maintaining three document parsers with three sets of conventions. Akinda's Financial data API and SEC filings API exist for that case: they return calculated figures, including interest-bearing debt, operating lease obligations and prohibited revenue by segment, each tied back to the filing it came from. Both sit alongside an MCP server and webhooks for teams that need updates rather than polling.

Keep EDGAR as the source of record either way. Even when a vendor supplies the calculation, store the accession alongside it, so an analyst can open the filing and check the number. Provenance is what makes a screening verdict defensible to a reviewer who disagrees with it.

A practical test settles the question in an afternoon. Run one CIK through submissions and company facts yourself, then list the figures your product needs that the tag set left blank. If the list is short and stable, raw EDGAR is enough. If it's long, or if it changes with every filing season, the extracted feed earns its place.


Akinda's SEC filings API returns AI-extracted figures from 10-K and 10-Q filings, each one stored with the filing it came from, so you can skip the accession joins and unit filters and start from a number you can defend. New submissions are analysed within 48 hours, which keeps a screening product current without a polling job of your own. Pick one ticker you already know well, pull its report, and compare it line by line against your own parse at Akinda.