# 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](https://www.sec.gov/search-filings/edgar-application-programming-interfaces) and checked with live requests on 2026-11-15.

## The SEC EDGAR API endpoints

SEC's [API page](https://www.sec.gov/search-filings/edgar-application-programming-interfaces) 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](https://www.sec.gov/search-filings/edgar-search-assistance/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:

```python
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](https://www.sec.gov/about/webmaster-frequently-asked-questions) 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](https://www.sec.gov/privacy.htm#security). 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.

```python
import time

import requests

USER_AGENT = "Your Name your.email@example.com"  # your own name and email
MIN_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.

```python
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"))  # 0000320193
```

The 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:

```python
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:

```python
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`:

- `CY2024` is a calendar year (a duration of 365 days, plus or minus 30).
- `CY2024Q1` is a quarter (91 days, plus or minus 30).
- `CY2024Q1I` is 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`.

```python
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](https://www.sec.gov/edgar/search/). The [Full-Text Search FAQ](https://www.sec.gov/edgar/search/efts-faq.html) 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.

```python
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](/guides/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](https://pypi.org/project/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](https://pypi.org/project/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](/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](/guides/fred-api-python), [Census API](/guides/census-api) and [ClinicalTrials.gov API v2](/guides/clinicaltrials-gov-api) guides, and for reading the filings themselves, [account research from a 10-K](/guides/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/
