Get USDA Foods (Batch)
usda_get_foodsFetch nutrient profiles for several foods at once. More efficient than calling usda_get_food N times when you already have multiple FDC IDs. Accepts up to 500 IDs: repeats are dropped, the first 20 distinct IDs are fetched, and the rest are returned in deferredIds for a follow-up call. IDs FDC does not return before the call's deadline (slow Foundation records, most often) or keeps failing on also come back in deferredIds, ahead of those, named in a notice. Values are per 100 of each food's basisUnit, with no portion scaling: per 100 g (basisUnit "g"), except Branded foods FDC reports per 100 ml (basisUnit "ml") or per 100 of a label unit that fixes neither (basisUnit absent, basis unverified). Use the nutrients[] filter to limit response size — strongly recommended for batch calls; requested IDs a food does not report are listed in its missingNutrients. Set provenance=true to add to each nutrient how FDC obtained its value (derivation code, description, and source), its sample count (dataPoints), and the sample min, max, and median, each only where FDC sends it. For side-by-side comparison with a formatted table, use usda_compare_foods instead. Failed IDs (not found or no data) are reported in the failed[] array rather than aborting the entire batch.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"fdcIds": "<fdcIds>"
},
"name": "usda_get_foods"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fdcIds | Yes | FDC IDs to fetch — 2 to 500 entries (a server configured with strict limits rejects more than 20). Repeats are dropped; the first 20 distinct IDs are fetched and the rest are returned in deferredIds. Use usda_search_foods to discover IDs. | |
| nutrients | No | Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended — full profiles can be large. Use usda_list_nutrients to look up IDs. Requested IDs a food does not report are listed in its missingNutrients. | |
| provenance | No | Add to each nutrient what FDC records about its value: derivation (code, description, source), dataPoints (sample count), and min, max, median (sample spread, per 100 of basisUnit like amount). Each is present only where FDC sends it: Survey (FNDDS) foods send none, Branded foods only a derivation. Off by default; it makes the response two to three times as large. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| foods | No | Successfully fetched foods. | |
| failed | No | IDs that returned no data. Check these with usda_search_foods to verify they exist. | |
| notice | No | Deferral notice when deferredIds is present: how many of the distinct IDs past the first 20 were not fetched, which fetched IDs FDC did not return before the deadline or kept failing on, and the call that fetches them. | |
| deferredIds | No | Distinct requested IDs this call did not fetch, in request order: any FDC did not return before the call's deadline or kept failing on, then those past the first 20, which were never requested from FDC. foods and failed cover neither. Pass them to usda_get_foods again, or a single one to usda_get_food, with the same nutrients and provenance. Absent when every distinct ID was fetched. |