Openfda Search Recalls
openfda_search_recallsRead-only
Search enforcement reports and recall actions across drugs, food, and devices. 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 (any letter case; :ascending and :descending are also accepted, and every direction is sent as asc or desc); comma-separate for multi-field sort (e.g. report_date:desc,status.exact:asc). Field paths take only letters, digits, underscores, and dots; any other character or direction is rejected before the request. A well-formed but non-sortable field still causes a query error — use a documented field name. | |
| 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 — page_bytes then reports its size and page_largest_fields names its largest fields, which fields can project away. Device records are the largest here — a device enforcement or recall record runs several kilobytes where a drug or food enforcement record is around one. | |
| 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. | |
| fields | No | Dotted record paths to keep on each returned record, e.g. ["recalling_firm", "reason_for_recall"] — any key path on a returned record works, and openfda_describe_fields lists the searchable ones. Each record is projected to these paths plus its identity key (recall_number, product_res_number) before the inline byte budget is measured, identically on both response surfaces, and a path through an array applies to every element. Use it when records are large: a page_bytes over the budget comes with the largest fields of the oversized record. A path no returned record carries is named on the notice. Omit for whole records. Paths take only letters, digits, underscores, and dots; anything else is rejected before the request. With stage=true, only the inline page is projected — the staged table keeps its columns. | |
| search | No | openFDA search query. Examples: classification:"Class I" (also "Class II" or "Class III"), recalling_firm:"pfizer", reason_for_recall:"undeclared allergen". 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 | |
| endpoint | No | Report type. Default enforcement. The recall endpoint is only available for devices. | enforcement |
| 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 fields projection and any requested path no record carries, the byte-budget disclosure when the inline page was bounded or one record exceeds it (with the routes to the withheld records and the largest fields of the oversized record), and guidance when results are empty — how to broaden filters or correct field names. | |
| results | No | Enforcement or recall records. Enforcement records (every category) carry recall_number, classification, status, voluntary_mandated, recalling_firm, product_description, reason_for_recall, distribution_pattern, report_date. Device recall records name identity product_res_number and status recall_status, add res_event_number and root_cause_description, share the firm, product, reason, and distribution fields, and carry no recall hazard classification. | |
| 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 UTF-8 bytes. Present when the 24000-byte inline budget bounded the page or when the page exceeds it; larger than the budget only when a single record exceeds it on its own, which is returned whole — page_largest_fields then names its largest fields, and fields projects the record to the paths you need. | |
| 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 records were dropped. Read them by re-calling with skip advanced by the number of records returned, lower limit for a smaller page (when more than one record came back), pass fields to keep only the paths you need, or pass stage=true to query a bounded drain of the match with openfda_dataframe_query. | |
| totalResults | No | Total matching recall/enforcement records in the dataset | |
| effectiveQuery | No | Search filter applied to the recall query, as submitted to openFDA | |
| projected_fields | No | The field paths each record in results was projected to, as requested — present only when the call passed fields. Every record also keeps its identity key; any other field is absent because the projection left it out, not because openFDA lacks it. Re-call without fields for whole records. | |
| page_largest_fields | No | Present only when page_bytes exceeds the 24000-byte budget, which happens only when the one record on the page exceeds it on its own: that record's largest fields, largest first — the deepest single field that holds the overrun, or else up to three top-level fields. Leave them out with a fields projection to shrink the record. |