NewAnswers MCP: one question, one checked answer for your agent.See how it works

Guides

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

By , founder of HyperresearchPublished

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 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 with the “Get your API key” button. The key is free, and signing up means you agree to openFDA’s terms of service.

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:

Terminal window
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:

{"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 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 and 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:

Terminal window
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:

Terminal window
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.

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:

Terminal window
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:

Terminal window
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:

Terminal window
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:

Terminal window
curl 'https://api.fda.gov/device/recall.json?skip=25001&limit=1'
{"error": {"code": "BAD_REQUEST", "message": "Skip value must 25000 or less."}}

For larger sets the Paging page 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:

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 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.

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:

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 reads openFDA records among its 120+ structured sources and quotes the record it cites.

Sources