Guides
SEC EDGAR API in Python: submissions, company facts, frames, and the User-Agent rule
The SEC EDGAR API is a set of free JSON endpoints on data.sec.gov that need no account or API key. Every request must declare a User-Agent header that names you and gives a contact email, and SEC’s fair access policy caps each user at 10 requests per second. Without that header, SEC answers with HTTP 403 and a page titled “Your Request Originates from an Undeclared Automated Tool”.
The endpoints cover each company’s filing history (submissions) and the XBRL financial data extracted from its reports (companyconcept, companyfacts and frames). Everything below was read from the EDGAR API documentation and checked with live requests on 2026-11-15.
The SEC EDGAR API endpoints
SEC’s API page says the data.sec.gov APIs “do not require any authentication or API keys to access” and are updated in real time as filings are disseminated. Every company URL takes the 10-digit CIK (Central Index Key) with its leading zeros. The table uses Apple, CIK 0000320193.
| Endpoint | What it returns | Example URL |
|---|---|---|
company_tickers.json |
Every ticker with its CIK and company name, for ticker-to-CIK lookups | https://www.sec.gov/files/company_tickers.json |
submissions |
Company metadata (name, tickers, exchanges, SIC, fiscal year end) and its filing history: at least one year or the 1,000 most recent filings, whichever is more | https://data.sec.gov/submissions/CIK0000320193.json |
xbrl/companyconcept |
Every value one company reported for one concept (taxonomy and tag), split by unit | https://data.sec.gov/api/xbrl/companyconcept/CIK0000320193/us-gaap/AccountsPayableCurrent.json |
xbrl/companyfacts |
Every concept one company has reported, in one file | https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json |
xbrl/frames |
One value per company for one concept and one calendar period | https://data.sec.gov/api/xbrl/frames/us-gaap/AccountsPayableCurrent/USD/CY2019Q1I.json |
| Full-text search | Filings whose text matches a query, since 2001 (the JSON behind sec.gov/edgar/search, not documented as an API) | https://efts.sec.gov/LATEST/search-index?q=%22material%20weakness%22&forms=10-K |
| Bulk ZIPs | All companyfacts or all submissions files, rebuilt nightly |
https://www.sec.gov/Archives/edgar/daily-index/xbrl/companyfacts.zip |
The XBRL endpoints carry statements from 10-Q, 10-K, 8-K, 20-F, 40-F and 6-K filings and their variants, and only facts in standard taxonomies such as us-gaap, ifrs-full, dei and srt. A company’s custom tags are not in them.
The User-Agent rule and why SEC EDGAR returns 403
SEC EDGAR returns 403 when a request carries no declared User-Agent, so set one header with your name or company and a contact email on every call. The Accessing EDGAR Data page gives the format as a sample: Sample Company Name AdminContact@<sample company domain>.com, alongside Accept-Encoding: gzip, deflate.
A request with no User-Agent, sent to the submissions endpoint on 2026-11-15, came back as 403 Forbidden with an HTML page that says:
Please declare your traffic by updating your user agent to include company specific information.
The page title is “SEC.gov | Your Request Originates from an Undeclared Automated Tool”. Python’s requests library sends python-requests/2.32.5 (or your installed version) by default, which names no one, so set the header yourself:
import requests
session = requests.Session()session.headers.update({"User-Agent": "Your Name your.email@example.com"})# requests already asks for gzip and deflate, so Accept-Encoding needs no change.The Webmaster FAQ answers its own “Undeclared Automated Tool” question with the same sample headers. Its separate “Access Denied” answer asks you to email webmaster@sec.gov with the error text and your IP address.
The EDGAR rate limit
The EDGAR rate limit is 10 requests per second per user, “regardless of the number of machines used to submit requests”, according to SEC’s Internet Security Policy. The policy adds that an IP address that goes over may be limited “for a brief period” and can resume once its request rate “has dropped below the threshold for 10 minutes”. SEC also reserves the right to block IP addresses that send excessive requests.
So spacing calls matters more than retrying them. The helper below waits at least 0.15 seconds between calls, which keeps one process under seven requests a second. If several processes share one IP, the 10 per second is shared too.
import time
import requests
USER_AGENT = "Your Name your.email@example.com" # your own name and emailMIN_INTERVAL = 0.15 # seconds between calls, under SEC's 10 per second
session = requests.Session()session.headers.update({"User-Agent": USER_AGENT})_last_call = 0.0
def sec_get(url, **params): """GET an SEC JSON endpoint politely and return the parsed body.""" global _last_call wait = MIN_INTERVAL - (time.monotonic() - _last_call) if wait > 0: time.sleep(wait) _last_call = time.monotonic() resp = session.get(url, params=params or None, timeout=30) if resp.status_code == 403: if "Undeclared Automated Tool" in resp.text: raise RuntimeError("SEC 403: set a User-Agent with your name and email") raise RuntimeError("SEC 403: possibly rate limited; pause for 10 minutes") resp.raise_for_status() return resp.json()For large jobs, SEC’s API page calls the nightly bulk ZIPs “the most efficient means to fetch large amounts of API data”. companyfacts.zip holds all the data behind the company facts and frames APIs, and submissions.zip holds every filer’s filing history. Both are republished at about 3:00 a.m. ET.
Mapping a ticker to a CIK
You map a ticker to a CIK with company_tickers.json, a file SEC publishes for its own EDGAR search box. It is a JSON object keyed by row number, and each row has cik_str (an integer), ticker and title; the copy fetched on 2026-11-15 had 10,404 rows. SEC says it updates the file periodically but does “not guarantee accuracy or scope”, so treat a missing ticker as a lookup to do by hand, not as proof the company does not file.
from functools import lru_cache
@lru_cache(maxsize=1)def _tickers(): rows = sec_get("https://www.sec.gov/files/company_tickers.json").values() return {row["ticker"]: row for row in rows}
def ticker_to_cik(ticker): """Return the 10-digit, zero-padded CIK for a ticker.""" row = _tickers()[ticker.upper()] return f"{row['cik_str']:010d}"
print(ticker_to_cik("aapl")) # 0000320193The zero padding is not optional. https://data.sec.gov/submissions/CIK0000320193.json returns Apple’s file, while CIK320193.json returns 404 with an XML NoSuchKey error. A sibling file, company_tickers_exchange.json, adds the exchange, and the full name-to-CIK list, funds and individuals included, is https://www.sec.gov/Archives/edgar/cik-lookup-data.txt.
Getting a company’s filings list
You get a company’s filings list from https://data.sec.gov/submissions/CIK##########.json. The file holds the company’s metadata and, under filings.recent, a columnar table: parallel arrays such as accessionNumber, filingDate, reportDate, form and primaryDocument, where index i in each array belongs to the same filing. Zip them into rows:
def filings(cik10, form=None): """Return the company name and its recent filings as a list of dicts.""" body = sec_get(f"https://data.sec.gov/submissions/CIK{cik10}.json") recent = body["filings"]["recent"] rows = [dict(zip(recent, values)) for values in zip(*recent.values())] if form: rows = [r for r in rows if r["form"] == form] return body["name"], rows
def filing_url(cik10, row): """Build the link to a filing's main document.""" folder = row["accessionNumber"].replace("-", "") return f"https://www.sec.gov/Archives/edgar/data/{int(cik10)}/{folder}/{row['primaryDocument']}"
name, tenks = filings("0000320193", form="10-K")latest = tenks[0]print(name, latest["filingDate"], latest["reportDate"], filing_url("0000320193", latest))On 2026-11-15, Apple’s filings.recent held 1,002 filings back to October 2015, and the latest 10-K was accession 0000320193-26-000026, filed 2026-11-03 for the year ended 2026-09-26. Older filings sit in extra files listed under filings.files; each entry gives a name, such as CIK0000320193-submissions-001.json, plus filingCount, filingFrom and filingTo. Fetch it from https://data.sec.gov/submissions/ followed by that name. Those files hold the same parallel arrays at the top level, with no recent wrapper.
Revenue for one company with companyconcept
You get one figure for one company over time from companyconcept, which returns every value the company reported for one XBRL tag, grouped under units (usually USD). Each fact carries start, end, val, fy, fp, form, filed and the accession number accn.
The same period appears more than once, because each 10-K repeats prior years as comparatives. A fact that SEC matched to a calendar period also has a frame key, such as CY2024, and only one fact per period gets it. Filter on that key to keep one annual value per year:
def annual_values(cik10, tag, taxonomy="us-gaap", unit="USD"): """One full-year value per period from 10-K filings: (frame, end, value).""" url = f"https://data.sec.gov/api/xbrl/companyconcept/CIK{cik10}/{taxonomy}/{tag}.json" facts = sec_get(url)["units"][unit] return [ (f["frame"], f["end"], f["val"]) for f in facts if f.get("form") == "10-K" and f.get("fp") == "FY" and "frame" in f and "Q" not in f["frame"] ]
for frame, end, val in annual_values("0000320193", "RevenueFromContractWithCustomerExcludingAssessedTax")[-3:]: print(frame, end, f"{val:,}")The hard part is the tag, not the request. Apple’s annual revenue is under SalesRevenueNet up to fiscal 2017, under Revenues for fiscal 2016 to 2018, and under RevenueFromContractWithCustomerExcludingAssessedTax from fiscal 2017 on, so the tags overlap and no single one covers the whole history. To see every tag a company has reported, fetch companyfacts once and list the keys under facts["us-gaap"]; Apple’s file had 512 us-gaap concepts on 2026-11-15.
One figure for every company with frames
You get one figure for every company in one period from frames, which the API page says “aggregates one fact for each reporting entity that is last filed that most closely fits the calendrical period requested”. The URL is /api/xbrl/frames/{taxonomy}/{tag}/{unit}/{period}.json:
CY2024is a calendar year (a duration of 365 days, plus or minus 30).CY2024Q1is a quarter (91 days, plus or minus 30).CY2024Q1Iis an instant, for balance sheet items such as cash or accounts payable.
Units with a numerator and a denominator use -per-, as in USD-per-shares.
def frame(tag, period, unit="USD", taxonomy="us-gaap"): """Every company's value for one tag and period, largest first.""" body = sec_get(f"https://data.sec.gov/api/xbrl/frames/{taxonomy}/{tag}/{unit}/{period}.json") return sorted(body["data"], key=lambda row: row["val"], reverse=True)
rows = frame("RevenueFromContractWithCustomerExcludingAssessedTax", "CY2024")for row in rows[:10]: print(row["entityName"], row["end"], f"{row['val']:,}")Each row carries accn, cik, entityName, loc, start, end and val, and the top-level pts gives the row count: 2,974 companies for that revenue tag in CY2024, and 3,390 for the AccountsPayableCurrent example in the table. Fiscal years are placed by best fit, so Apple’s year from 2023-10-01 to 2024-09-28 sits in CY2024 with $391,035,000,000. Check start and end before comparing companies, and remember that a company reporting revenue under a different tag is simply absent from this frame.
Searching the full text of filings
You search the text of filings through https://efts.sec.gov/LATEST/search-index, the JSON service behind EDGAR Full-Text Search. The Full-Text Search FAQ says it covers “all EDGAR filings submitted electronically since 2001”, attachments included. SEC does not document this endpoint as an API, so the parameters below are the ones its search page sends, confirmed with live calls on 2026-11-15.
def full_text_search(query, forms=None, start=None, end=None, page=0): """One page (up to 100 hits) of EDGAR full-text search results.""" params = {"q": query} if forms: params["forms"] = forms # e.g. "10-K" or "10-K,10-Q" if start and end: params.update(dateRange="custom", startdt=start, enddt=end) if page: params["from"] = page * 100 body = sec_get("https://efts.sec.gov/LATEST/search-index", **params) hits = [] for hit in body["hits"]["hits"]: accession, filename = hit["_id"].split(":", 1) src = hit["_source"] cik = int(src["ciks"][0]) folder = accession.replace("-", "") hits.append({ "company": src["display_names"][0], "form": src["form"], "filed": src["file_date"], "url": f"https://www.sec.gov/Archives/edgar/data/{cik}/{folder}/{filename}", }) return body["hits"]["total"]["value"], hits
total, hits = full_text_search('"material weakness"', forms="10-K", start="2026-01-01", end="2026-11-14")print(total, hits[0])That query matched 3,979 filings, returned 100 per page, and from=100 returned the second page. The forms=10-K filter matches on the root form, so 10-K/A amendments come back too; check form if you want originals only. Query syntax follows the FAQ: quotes for an exact phrase, capitalized OR and NOT (or a leading hyphen), NEAR(5) for proximity, and a trailing * for stems. Search is case insensitive, and every term is required by default.
For an example of what this endpoint supports at scale, the AI coding agents in SEC filings guide counts, quarter by quarter, the companies whose filings name GitHub Copilot, Cursor and other AI coding tools, built from EDGAR full-text search.
Python packages for EDGAR
Two packages on PyPI wrap these endpoints if you would rather not write the calls yourself. edgartools (version 6.2.0, uploaded 2026-11-15, Python 3.11 or later) describes itself as a library for EDGAR filings and XBRL financial statements. sec-edgar-downloader (version 5.1.0, uploaded 2026-02-02, Python 3.10 or later) downloads filings from EDGAR. Whichever you use, SEC’s User-Agent and 10-per-second rules still apply to the requests it sends, and for the endpoints above, the plain requests helpers are short enough that a dependency is optional.
Using EDGAR next to other sources
Hyperresearch reads SEC EDGAR filings, XBRL financial statements and full-text search as one of its 120+ data sources, for teams that want filing figures cited in a report rather than raw JSON. For other public data APIs, see the FRED API in Python, Census API and ClinicalTrials.gov API v2 guides, and for reading the filings themselves, account research from a 10-K.
Sources
- EDGAR Application Programming Interfaces: https://www.sec.gov/search-filings/edgar-application-programming-interfaces
- Accessing EDGAR Data: https://www.sec.gov/search-filings/edgar-search-assistance/accessing-edgar-data
- Developer Resources: https://www.sec.gov/about/developer-resources
- Webmaster Frequently Asked Questions: https://www.sec.gov/about/webmaster-frequently-asked-questions
- Privacy and Security Policy (Internet Security Policy): https://www.sec.gov/privacy.htm#security
- EDGAR Full-Text Search FAQ: https://www.sec.gov/edgar/search/efts-faq.html
- company_tickers.json: https://www.sec.gov/files/company_tickers.json
- Bulk company facts: https://www.sec.gov/Archives/edgar/daily-index/xbrl/companyfacts.zip
- Bulk submissions: https://www.sec.gov/Archives/edgar/daily-index/bulkdata/submissions.zip
- edgartools on PyPI: https://pypi.org/project/edgartools/
- sec-edgar-downloader on PyPI: https://pypi.org/project/sec-edgar-downloader/
