Openfda Search Adverse Events
openfda_search_adverse_eventsRead-only
Search adverse event reports across drugs, food, and devices. Use to investigate safety signals, find reports for a specific product, or explore reactions by demographics. With stage=true, call openfda_dataframe_describe for the staged columns, then openfda_dataframe_query for SQL.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip for pagination (default 0). openFDA caps pagination at 25000 records; a higher value returns a pagination_limit_reached error. | |
| sort | No | Sort expression — a field path optionally suffixed with :asc or :desc; comma-separate for multi-field sort. Field paths take only letters, digits, underscores, and dots; anything else is rejected before the request. Sortable date fields are category-specific: drug → receivedate:desc (or receiptdate), food → date_created:desc (or date_started), device → date_received:desc (or date_of_event). A field from another category (e.g. receivedate on food or device) causes a query error — use the field for this category. | |
| limit | No | Maximum number of records to return (1-1000, default 10). Serialized record size varies by three orders of magnitude across openFDA endpoints, so the page is also bounded by a 24000-byte serialized budget: a page that would overrun it returns fewer records than requested and reports the cut on page_omitted. Whenever any record matched, at least one comes back, however large it measures. Drug reports are by far the largest — a single drug/event report averages tens of kilobytes where a food/event report is a few hundred bytes. | |
| stage | No | Stage the matched set on a DataCanvas for SQL analysis — openfda_dataframe_describe lists the staged columns, openfda_dataframe_query runs the SQL. Default false — the call returns one page for one upstream request. When true, records are also drained onto a canvas table up to a size budget (staged_rows reports how many reached it). Staging is for record-level SQL over a bounded slice; for a distribution over everything that matched, openfda_count_values aggregates server-side in one request. Requires CANVAS_PROVIDER_TYPE=duckdb. | |
| search | No | openFDA search query. Examples: patient.drug.medicinalproduct:"aspirin", patient.reaction.reactionmeddrapt:"nausea" AND serious:"1". Omit to browse recent. Double quotes, parentheses, and range brackets must balance, and the query must not end on a backslash — each is rejected before the request. | |
| category | Yes | Product category — each has different field schemas in the response | |
| canvas_id | No | Canvas ID returned by a prior stage=true call to this tool or another openFDA search tool (openfda_search_* or openfda_lookup_ndc). Passing one stages this search onto that canvas (same effect as stage=true) so result sets accumulate for cross-table joins. Omit to stage onto a fresh canvas. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Response metadata | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Canvas staging disclosure when the call staged, the byte-budget disclosure and the routes to the withheld records when the inline page was bounded, and guidance when results are empty or paging overshot — how to broaden filters or adjust the query. | |
| results | No | Adverse event records — fields vary by category (drug: patient/reactions/drugs, device: device details/event type, food: products/outcomes) | |
| spilled | No | True when this call staged its matched set on the canvas — use canvas_id with openfda_dataframe_describe for its columns, then openfda_dataframe_query for SQL. Absent when staging was not requested. | |
| canvas_id | No | DataCanvas session id for the staged result set. Present when this call staged. Pass to openfda_dataframe_query / openfda_dataframe_describe, or back into this tool to accumulate more tables on the same canvas. | |
| truncated | No | True when fewer rows reached the canvas than matched upstream — staging stopped at its size budget or openFDA's 25000-row pagination ceiling. Narrow the query (filters, date range) for a complete set. | |
| page_bytes | No | Serialized size of results in this response, in bytes. Present only when the 24000-byte inline budget bounded the page; larger than the budget only when a single record exceeds it on its own. | |
| staged_rows | No | Rows written to the canvas table. Compare with meta.total: a smaller value means staging stopped at its size budget and the table holds only the first staged_rows records. | |
| canvas_table | No | Canvas table holding the staged rows. Present when rows were staged; list its columns with openfda_dataframe_describe, then reference it in openfda_dataframe_query FROM clauses. | |
| page_omitted | No | Records dropped from the requested limit/skip window so the page fit the inline byte budget. Present only when the page was bounded. Read them by re-calling with skip advanced by the number of records returned, lower limit for a smaller page, or pass stage=true to query a bounded drain of the match with openfda_dataframe_query. | |
| totalResults | No | Total matching adverse event records in the dataset | |
| effectiveQuery | No | Search filter applied to the query, as submitted to openFDA |