# openFDA API: endpoints, API key, rate limits and Python examples

The openFDA API is the U.S. Food and Drug Administration's free JSON API at `https://api.fda.gov`, with separate endpoints for drug adverse events, drug labels, recalls, device reports and food data. You can call it without a key at 240 requests per minute and 1,000 requests per day per IP address; a free API key keeps the 240 per minute and raises the daily cap to 120,000 requests per key. Each query goes to one endpoint, such as `/drug/event.json`, and filters with `search=field:term`, counts with `count=field`, and pages with `limit` (up to 1,000) and `skip` (up to 25,000) or with the `search_after` link in the response headers.

Everything below was read from the [openFDA API documentation](https://open.fda.gov/apis/) and checked with live requests to `api.fda.gov` on November 17, 2026. The totals quoted are from those requests and will grow as FDA adds data.

## How to get an openFDA API key

You get a key from the [Authentication page](https://open.fda.gov/apis/authentication/) with the "Get your API key" button. The key is free, and signing up means you agree to openFDA's [terms of service](https://open.fda.gov/terms/).

The docs are not fully consistent about whether you need one. The Authentication page opens with "An API key is required to make calls to the openFDA API," yet the same page lists limits for calls with no key, and the drug adverse event guide says you don't need a key to try or use the API but should get one for regular use. In practice every request in this guide worked without a key.

Pass the key as the `api_key` parameter, placed before the other parameters:

```bash
curl -g 'https://api.fda.gov/drug/event.json?api_key=YOUR_API_KEY&search=receivedate:[20250101+TO+20251231]&limit=1'
```

You can also send it as the username in HTTP Basic auth (`Authorization: Basic` plus the base64 of `YOUR_API_KEY:`). openFDA accepts HTTPS only. A wrong key fails at once with HTTP 403:

```json
{"error": {"code": "API_KEY_INVALID", "message": "An invalid api_key was supplied. Get one at https://api.fda.gov:443"}}
```

## openFDA API rate limits with and without a key

The limits on the Authentication page, read November 17, 2026:

| Access | Per minute | Per day | Counted by |
|---|---|---|---|
| No API key | 240 requests | 1,000 requests | IP address |
| Free API key | 240 requests | 120,000 requests | key |

The key raises the daily cap and counts requests by key instead of by IP address; the per-minute rate stays the same. If you need more than a key allows, the page asks you to contact openFDA. Keyless responses we received carried no `X-RateLimit` headers, so count your own requests rather than reading a remaining figure from the response.

Two more limits apply to every query, from the [Query parameters](https://open.fda.gov/apis/query-parameters/) page: `limit` can be at most 1,000 records per call, and `skip` at most 25,000. A `count` query returns the 1,000 most frequent values by default.

## openFDA API endpoints

Every endpoint is `https://api.fda.gov/{noun}/{category}.json`. The update frequency and start year come from each endpoint's Key Facts on open.fda.gov; the record counts come from openFDA's download index (`https://api.fda.gov/download.json`) on November 17, 2026.

| Endpoint | Contents | Updated | Records |
|---|---|---|---|
| `/drug/event.json` | Drug adverse event and medication error reports (FAERS), 2004 on | Quarterly, may lag 3 months or more | 21,054,159 |
| `/drug/label.json` | Structured product labels for prescription and OTC drugs, mostly June 2009 on | Weekly | 264,801 |
| `/drug/ndc.json` | National Drug Code directory | Daily | 138,487 |
| `/drug/enforcement.json` | Drug recall enforcement reports, 2004 on | Weekly | 18,166 |
| `/drug/drugsfda.json` | Drugs@FDA approvals, most products since 1939 | Daily (Monday to Friday) | 29,460 |
| `/drug/shortages.json` | Drug shortages, 2012 on | Daily | 1,585 |
| `/device/event.json` | Device adverse event reports (MAUDE), 2009 on | Weekly | 26,849,547 |
| `/device/recall.json` | Medical device recalls, 2002 on | Weekly | 59,705 |
| `/device/enforcement.json` | Device recall enforcement reports, 2004 on | Weekly | 40,535 |
| `/device/510k.json` | 510(k) clearances, 1976 on | Monthly | 176,683 |
| `/device/classification.json` | Device names, product codes and classes | Monthly | 7,103 |
| `/food/enforcement.json` | Food recall enforcement reports, 2004 on | Weekly | 29,609 |
| `/food/event.json` | Food, dietary supplement and cosmetic adverse events (CAERS), 2004 on | Quarterly | 151,589 |

The same index also lists device PMA, UDI and registration endpoints, the Orange Book, animal and veterinary events, tobacco problem reports and several research and reference sets.

"Adverse events vs labels vs recalls" maps to three different datasets. Side-effect reports are in `drug/event` (or `device/event`), what the label says is in `drug/label`, and recalls are in `drug/enforcement`, `device/recall`, `device/enforcement` and `food/enforcement`.

## How openFDA search and count queries work

A query is `search=field:term`, with one equals sign and a colon between the field and the term. The rules from the [query syntax](https://open.fda.gov/apis/query-syntax/) and [advanced syntax](https://open.fda.gov/apis/advanced-syntax/) pages:

- Use `+` for every space, and double quotes for a phrase: `"metformin+hydrochloride"`.
- `+AND+` requires both terms; terms joined by a bare `+` match either.
- Group with parentheses: `patient.drug.medicinalproduct:(cetirizine+OR+loratadine)`.
- Date ranges use `[START+TO+END]` with `YYYYMMDD` dates.
- `sort=field:asc` or `:desc` orders the results.
- Without `limit`, a search returns one record.

Each response has a `meta` block and a `results` array. `meta.results.total` is the number of matching records and `meta.last_updated` is the data date:

```bash
curl -g 'https://api.fda.gov/drug/event.json?search=receivedate:[20250101+TO+20251231]&limit=1'
```

On November 17, 2026 that returned `"total": 1307794` reports received in 2025, with `"last_updated": "2026-10-28"`.

A count query returns terms and their frequencies instead of records. Add `.exact` to count whole phrases rather than single words:

```bash
curl 'https://api.fda.gov/drug/event.json?count=patient.reaction.reactionmeddrapt.exact&limit=5'
```

The top five reactions across all drug event reports that day were DRUG INEFFECTIVE (1,319,251), OFF LABEL USE (876,519), DEATH (862,390), NAUSEA (792,255) and FATIGUE (779,339). Counting on a date field, such as `count=receiptdate`, returns a daily [time series](https://open.fda.gov/apis/timeseries/).

These are counts of reports, not of people harmed. FDA's own disclaimer says a report does not show the drug caused the reaction and the data cannot be used to estimate how often an event happens. Nothing here is medical advice; talk to a doctor or pharmacist about a medicine.

## openFDA drug API examples

Drug labels, searched on the harmonized generic name that openFDA adds to records:

```bash
curl 'https://api.fda.gov/drug/label.json?search=openfda.generic_name:"metformin+hydrochloride"&limit=1'
```

This matched 345 labels on November 17, 2026 (`last_updated` 2026-11-17), including combination products whose generic name contains the phrase.

Adverse event reports that list a drug, on the harmonized field:

```bash
curl 'https://api.fda.gov/drug/event.json?search=patient.drug.openfda.generic_name.exact:"ATORVASTATIN+CALCIUM"&limit=1'
```

Class I food enforcement reports dated in 2025:

```bash
curl -g 'https://api.fda.gov/food/enforcement.json?search=classification:"Class+I"+AND+report_date:[20250101+TO+20251231]&limit=1'
```

That returned 773 reports (`last_updated` 2026-11-11). `count=classification.exact` on the same search confirmed all 773 are "Class I". The `-g` flag stops curl from reading the square brackets as a pattern.

## Paging past 25,000 results with search_after

`skip` and `limit` let you reach the first 26,000 matches: `skip` up to 25,000 plus one more page of 1,000. One past that fails:

```bash
curl 'https://api.fda.gov/device/recall.json?skip=25001&limit=1'
```

```json
{"error": {"code": "BAD_REQUEST", "message": "Skip value must 25000 or less."}}
```

For larger sets the [Paging page](https://open.fda.gov/apis/paging/) describes `search_after`. Run the first query without `skip`, read the `Link` response header, and request the URL marked `rel="next"`. Repeat until the header is gone, which means you are on the last page. `skip` and `search_after` cannot be combined. A response header looked like this on November 17, 2026:

```text
Link: <https://api.fda.gov/drug/event.json?search=patient.reaction.reactionmeddrapt%3A%22fatigue%22&limit=1&skip=0&search_after=0%3D10003316>; rel="next"
```

For a whole dataset, the [downloads](https://open.fda.gov/apis/downloads/) are the same JSON as the API in zipped parts; `drug/event` alone is 1,799 files. openFDA notes that any record can change on each update, so you re-download every file rather than only new ones.

## openFDA API in Python

This program uses `requests`, which exposes the `Link` header as `r.links`. It pages through every match with `search_after`, treats "No matches found!" as zero results, and adds a key from the `OPENFDA_API_KEY` environment variable if you set one.

```python
import os
import requests

BASE = "https://api.fda.gov"
HEADERS = {"User-Agent": "my-app/1.0"}
API_KEY = os.environ.get("OPENFDA_API_KEY")  # optional


class OpenFDAError(Exception):
    pass


def openfda_get(url, params=None):
    params = dict(params or {})
    if API_KEY and "api_key=" not in url:
        params["api_key"] = API_KEY
    r = requests.get(url, params=params, headers=HEADERS, timeout=60)
    body = r.json()
    if r.status_code == 404 and body.get("error", {}).get("code") == "NOT_FOUND":
        return r, {"meta": {"results": {"total": 0}}, "results": []}
    if r.status_code != 200:
        err = body.get("error", {})
        raise OpenFDAError(f"HTTP {r.status_code} {err.get('code')}: {err.get('message')}")
    return r, body


def search_all(endpoint, search, limit=1000, max_records=None):
    """Yield every matching record, following the Link header (search_after)."""
    url = f"{BASE}/{endpoint}.json"
    params = {"search": search, "limit": limit}
    seen = 0
    while url:
        r, body = openfda_get(url, params)
        for rec in body.get("results", []):
            yield rec
            seen += 1
            if max_records and seen >= max_records:
                return
        url = r.links.get("next", {}).get("url")  # absent on the last page
        params = None  # the next URL already carries every parameter


def count(endpoint, field, search=None, limit=10):
    params = {"count": field, "limit": limit}
    if search:
        params["search"] = search
    _, body = openfda_get(f"{BASE}/{endpoint}.json", params)
    return body["results"]


if __name__ == "__main__":
    # Device recalls initiated in January 2025, paged 100 at a time
    recalls = list(search_all(
        "device/recall",
        "event_date_initiated:[20250101 TO 20250131]",
        limit=100,
    ))
    print(len(recalls), "device recalls initiated in January 2025")
    print(recalls[0]["product_res_number"], recalls[0]["recall_status"])

    # Top reactions in adverse event reports that list atorvastatin calcium
    for row in count(
        "drug/event",
        "patient.reaction.reactionmeddrapt.exact",
        search='patient.drug.openfda.generic_name.exact:"ATORVASTATIN CALCIUM"',
        limit=5,
    ):
        print(row["term"], row["count"])
```

Run without a key on November 17, 2026, it made three requests (two pages of recalls, one count) and printed:

```text
177 device recalls initiated in January 2025
Z-0922-2025 Open, Classified
FATIGUE 14464
DRUG INEFFECTIVE 13345
NAUSEA 12922
DIARRHOEA 11692
DYSPNOEA 11668
```

`requests` encodes the spaces in `search` itself, so you write normal spaces there instead of `+`. At 1,000 records per page, the keyless 1,000-requests-a-day cap allows about one million records a day.

## openFDA API errors and fixes

These are the bodies the API returned on November 17, 2026.

| Status | Body | Cause and fix |
|---|---|---|
| 404 | `{"error": {"code": "NOT_FOUND", "message": "No matches found!"}}` | No record matched. The same 404 comes back for a misspelled field name, so check the field against the endpoint's searchable fields before concluding there is no data. |
| 400 | `"Skip value must 25000 or less."` | `skip` above 25,000. Narrow the search or page with `search_after`. |
| 400 | `"Limit cannot exceed 1000 results for search requests. Use the skip or search_after param to get additional results."` | `limit` above 1,000. |
| 500 | `{"code": "SERVER_ERROR", "message": "Check your request and try again", "details": "[parse_exception] ..."}` | A malformed query, here an unclosed date range. Check brackets, quotes and `+TO+`. |
| 403 | `"code": "API_KEY_INVALID"` | A wrong or mistyped `api_key`. Remove it to test keyless, or copy the key again. |

A bad query can come back as a 500, so do not retry every 500 blindly; read `details` first.

## Why openFDA counts differ from the FAERS public dashboard

openFDA totals rarely match the FAERS Public Dashboard, and the reasons on the openFDA side can be seen in the data. (FDA now calls the system the FDA Adverse Event Monitoring System, AEMS, "formerly FAERS"; openFDA's docs still say FAERS.)

- **Coverage and timing.** The `drug/event` endpoint covers 2004 on and is refreshed quarterly, and the docs warn it may lag by three months or more. On November 17, 2026 its `last_updated` was 2026-10-28.
- **Word search versus exact terms.** A search for `reactionmeddrapt:"fatigue"` matched 785,183 reports, while the exact term FATIGUE counted 779,339, because the word search also hits longer reaction terms that contain "fatigue".
- **Which drug field you search.** `patient.drug.medicinalproduct:"atorvastatin"` matched 352,658 reports, while the harmonized `patient.drug.openfda.generic_name.exact:"ATORVASTATIN CALCIUM"` matched 248,656. The first is a word search on the product name as reported, so it catches any reported name containing the word, combination products included, and misses reports that used only a brand name; the second is the one exact generic name openFDA attached where it could match the product.
- **Reports, duplicates and follow-ups.** FDA says the system holds duplicate and incomplete reports, and openFDA says follow-up information arrives as separate reports rather than edits. A report can also list several drugs and several reactions without linking any drug to any reaction.

FDA does not reconcile the two tools on the pages we read, so state which tool, field, date range and data date your number comes from.

Hyperresearch's [Answers](/answers) reads openFDA records among its 120+ structured sources and quotes the record it cites.

## Sources

- openFDA, About the openFDA API: https://open.fda.gov/apis/
- openFDA, Authentication (API key and limits): https://open.fda.gov/apis/authentication/
- openFDA, Query syntax: https://open.fda.gov/apis/query-syntax/
- openFDA, Advanced syntax: https://open.fda.gov/apis/advanced-syntax/
- openFDA, Query parameters: https://open.fda.gov/apis/query-parameters/
- openFDA, Paging: https://open.fda.gov/apis/paging/
- openFDA, Timeseries: https://open.fda.gov/apis/timeseries/
- openFDA, Downloads: https://open.fda.gov/apis/downloads/
- openFDA, Drug adverse event overview: https://open.fda.gov/apis/drug/event/
- openFDA, Drug labeling overview: https://open.fda.gov/apis/drug/label/
- openFDA, Device recall overview: https://open.fda.gov/apis/device/recall/
- openFDA, Food enforcement overview: https://open.fda.gov/apis/food/enforcement/
- openFDA, download index: https://api.fda.gov/download.json
- FDA, FDA Adverse Event Monitoring System (AEMS), formerly FAERS: https://www.fda.gov/drugs/surveillance-post-drug-approval-activities/fda-adverse-event-monitoring-system-aems
- FDA, AEMS Public Dashboard: https://www.fda.gov/drugs/fda-adverse-event-monitoring-system-aems/fda-adverse-event-monitoring-system-aems-public-dashboard
