What this guide covers
What openFDA is (and the device endpoints)
openFDA is the FDA's public API programme. It publishes several device datasets as JSON over HTTPS, and you don't need to authenticate to get started. The one that maps to MAUDE is device/event. The others are useful for cross-referencing:
| Endpoint | Dataset |
|---|---|
/device/event.json | MAUDE adverse-event reports (MDRs) |
/device/recall.json | Device recalls |
/device/enforcement.json | Recall enforcement reports |
/device/510k.json | 510(k) clearances |
/device/classification.json | Product-code classifications |
/device/udi.json | GUDID / UDI device records |
/device/registrationlisting.json | Establishment registrations & listings |
The rest of this guide uses device/event, but the syntax is the same for all of them.
Anatomy of a request
Every request is a single GET URL. The base is:
https://api.fda.gov/device/event.json
You shape it with four query parameters:
search: the query (field:value expressions). Leave it out to match everything.count: return counts for a field instead of the records themselves.limit: how many records to return (max 1000; default 1).skip: offset for pagination (max 25000).
A minimal real query, returning the first of one manufacturer's reports:
https://api.fda.gov/device/event.json?search=
device.manufacturer_d_name:"ACME+MEDICAL"&limit=1
The response has two parts: a meta object (including meta.results.total, the full match count, even when you only pulled one record) and a results array. Check meta.results.total first to see how big a query is before you paginate it.
Search syntax
The search value is a Lucene-style expression. These are the pieces you'll use:
| Goal | Syntax |
|---|---|
| Field equals term | event_type:Malfunction |
| Exact phrase (spaces) | device.generic_name:"INFUSION+PUMP" |
| AND / OR | a:x+AND+b:y · a:x+OR+a:z |
| Grouping | event_type:(Death+OR+Injury) |
| Date / numeric range | date_received:[20250101+TO+20251231] |
| Field exists | _exists_:device.device_report_product_code |
| Wildcard | device.brand_name:acme* |
Two rules will save you a lot of confusion: spaces in a phrase become + (URL-encoding), and dates use YYYYMMDD with no separators. Here is a query that combines a manufacturer, an event type and a date range:
https://api.fda.gov/device/event.json?search=
device.manufacturer_d_name:"ACME+MEDICAL"
+AND+event_type:(Death+OR+Injury)
+AND+date_received:[20250101+TO+20251231]&limit=100
The fields you'll use
MAUDE records are deeply nested. These are the fields you'll query most for device monitoring:
| Field | What it is |
|---|---|
device.brand_name | Trade name on the report |
device.generic_name | Generic/common device name |
device.manufacturer_d_name | Manufacturer as reported |
device.model_number · device.catalog_number | Model and catalogue number as reported (free text, so expect spelling variants) |
device.device_report_product_code | Three-letter FDA product code (the most reliable field to search on) |
event_type | Death · Injury · Malfunction · (No answer/Other) |
date_received | Date FDA received the report |
date_of_event | Date of the incident (often blank) |
report_number | Report identifier (used to de-duplicate) |
product_problems | Coded problem descriptions |
device.openfda.* | Harmonised fields: device_class, regulation_number, medical_specialty_description |
The device.openfda object is worth knowing about. It adds the harmonised classification data to each record, so you can filter by device class or medical specialty without a second lookup.
Counting & aggregation (the .exact rule)
The count parameter gives you totals instead of records: how often each value of a field appears. That's how you get a breakdown by event type, or the top product codes for a manufacturer, in a single call. There's one rule that catches most people out:
.exact when counting text fields. count=event_type returns a SERVER_ERROR ("Text fields are not optimised for … aggregations"). You must write count=event_type.exact. The .exact suffix counts the whole field value as written rather than individual words. That's what you want anyway, or "infusion pump" would be counted as "infusion" and "pump" separately.Working count queries:
# Breakdown of a manufacturer's reports by event type
...?search=device.manufacturer_d_name:Medtronic&count=event_type.exact
# Top product codes a manufacturer is reported under
...?search=device.manufacturer_d_name:Medtronic
&count=device.device_report_product_code.exact
# Device-class split (openfda numeric field — no .exact needed)
...?search=device.manufacturer_d_name:Medtronic&count=device.openfda.device_class
Note the last one: device.openfda.device_class is not a free-text field, so it counts without .exact. Rule of thumb: text → .exact; keyword/numeric → plain.
Pagination & limits
Two hard limits affect how you pull large result sets:
limitmaxes at 1000 per request. Ask for more and you getBAD_REQUEST.skipmaxes at 25000. Soskip-based paging can only reach the first 25,000 records of a result set (26,000 total with a finallimit=1000page).
MAUDE queries often return more than that. A broad event_type:Malfunction search returns millions of records. You have two options:
search_after: openFDA's cursor pagination. Each response carries a token in its HTTPLinkheader (rel="next"). Pass it assearch_afteron the next call to keep going past the 25,000 limit.- Splitting by date: break the query into monthly or quarterly
date_receivedranges, each small enough to page normally. This is often simpler for scheduled monitoring, because you only want what's new since the last run anyway.
meta.results.total first. Under ~26,000 → page with skip. Over it → chunk by date_received, or use search_after.Rate limits & API keys
Without a key, openFDA allows 1,000 requests/day and 240/minute per IP. A free API key (register at open.fda.gov) raises the daily limit to 120,000 requests/day, same 240/minute. For anything scheduled, get a key and add it to each request:
...?search=event_type:Malfunction&limit=1000&api_key=YOUR_KEY
Keep the key on your server. It's tied to your request allowance, and anyone can use a key they find in front-end code. Handle 429 Too Many Requests by backing off and retrying, and cache results. The data only refreshes now and then, so pulling the same date range again a few minutes later wastes requests.
Common mistakes
- Filter on
date_received, notdate_of_event. The event date is often blank, so date-of-event ranges drop most records without any warning. The received date is always filled in, and it's what you want for monitoring new reports anyway. - Use
.exactfor counting or sorting text fields. As above, leaving it out is the most common cause ofSERVER_ERROR. - De-duplicate by
report_number. One event generates an initial report plus follow-ups (supplements); count events, not rows, by grouping on the report number. - Model numbers are free text.
device.model_numberanddevice.catalog_numberare searchable, but they are entered as reported, so one model can appear under several spellings. Search the variants, and combine with manufacturer and product code. - Redactions. Narrative text may contain
(b)(4)/(b)(6)where content was withheld. Make sure your code expects it. - Freshness lag. The dataset refreshes on the FDA's schedule (roughly weekly), and manufacturer MDRs arrive on reporting timelines, so the most recent weeks are always incomplete.
These are API mechanics. MAUDE also has limits on what the data can tell you: it can't prove causation or support rate calculations. Those are covered in our guide to searching and monitoring the MAUDE database, which this article accompanies.
A worked monitoring query
To put it together: a weekly job watching one product code for new death and injury reports would, on each run, read the total for the new date range and then page through it.
# 1. How many new serious reports this week for product code DZE?
https://api.fda.gov/device/event.json?search=
device.device_report_product_code:DZE
+AND+event_type:(Death+OR+Injury)
+AND+date_received:[20260717+TO+20260724]
&limit=1&api_key=YOUR_KEY
# -> read meta.results.total
# 2. Pull them (page with skip if total > 1000)
...&limit=1000&skip=0
...&limit=1000&skip=1000 # next page, etc.
De-duplicate the results by report_number, triage by event_type, read the narrative for context, and log what you found. Run it on a schedule keyed to date_received and you have a monitoring loop.
That covers one product code, one endpoint and one regulator. A whole portfolio means dozens of product codes and brand-name variants, all de-duplicated and matched to your devices. You also have to combine the results with the other regulator sources, whose feeds are less consistent than openFDA's. At that point a home-made script becomes hard to maintain.
The openFDA API is one source of many
MedFortis runs this daily across openFDA, the MHRA, Health Canada, Swissmedic, EUDAMED and other national sources. Results are matched to your device lines, de-duplicated and logged. Book a demo to see it on your own devices.
Book a Demo →Key takeaways
- MAUDE lives at
api.fda.gov/device/event.json; the same syntax covers recalls, 510(k)s, classification and UDI. - Read
meta.results.totalbefore paginating;limitcaps at 1000 andskipat 25000. Beyond that, usesearch_afteror split bydate_received. - Count text fields with
.exact(keyword and numeric fields don't need it). Forgetting it is the most common error. - Filter on
date_receivednotdate_of_event, de-duplicate byreport_number, and get a free API key for scheduled use (120k/day).