# USDA Foundation Foods (`waztap/usda-foundation-foods`) Actor

Source: U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, 2026. fdc.nal.usda.gov https://fdc.nal.usda.gov/
Waztap is independent and is not affiliated with or endorsed by USDA.
https://waztap.com/terms/ https://waztap.com/acceptable-use/ https://waztap.com/privacy/

- **URL**: https://apify.com/waztap/usda-foundation-foods.md
- **Developed by:** [Waztap](https://apify.com/waztap) (community)
- **Stats:** 2 total users, 1 monthly users, 66.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 completed operations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

Publisher: Waztap.

### USDA Foundation Foods

Search USDA Foundation Foods by description or reported protein per 100 g, inspect one food's accepted nutrient measurements, or retrieve dataset provenance and verification metadata. Each run performs one operation against Waztap's selected dataset version.

Coverage is the Foundation Foods core and accepted food-nutrient measurements. Branded Foods, FNDDS, SR Legacy, portions, recipes, photographs and full laboratory drill-down are excluded. This dataset supports research and is not medical or dietary advice.

### Start with one operation

Retrieve metadata with this complete input:

```json
{
  "operation": "dataset"
}
```

Search one page:

```json
{
  "operation": "search",
  "query": {
    "q": "beans",
    "limit": 1
  }
}
```

Retrieve one detail record:

```json
{
  "operation": "detail",
  "fdc_id": "1104647"
}
```

The detail identifier above is an example observed during validation. Prefer an identifier from a fresh search. Omit query for dataset/detail, and omit the detail ID for dataset/search. Do not fill inactive controls with blank strings.

Use **256 MB memory**, a **60-second timeout** and restart on error Off. Maximum cost per run may be **Unlimited** (omit `maxTotalChargeUsd` in an API request) or a finite amount of at least **$0.002**. One completed operation requests one $0.002 event; the spending limit is a ceiling, not an extra charge. A finite budget below one event is refused before the source request or output writes.

### Input fields

| Field | Use and behavior |
| --- | --- |
| operation | dataset, search or detail. The only default and prefill is dataset. Empty JSON input {} also selects dataset; nonempty input must specify the operation. No query or detail ID is prefilled. |
| fdc_id | Required only for detail. Positive integer string of 1 to 19 digits, no leading zero, and at most 9223372036854775807. Keep the ID as a string and use an identifier returned by search. |
| query | Optional only for search. Omit it for dataset and detail. |
| query.q | Nonblank simple full-text description search, at most 200 characters. Leading/trailing whitespace is trimmed and internal whitespace collapsed. |
| query.min_protein_g_per_100g | Nonnegative decimal string, such as "5" or "5.25". At most 26 integer digits and 12 fractional digits, no exponent or leading zeros. Missing or ambiguous protein summaries are excluded. |
| query.limit | Integer from 1 to 50. Runtime search default 20. Keep unchanged for continuation. |
| query.cursor | Opaque next_cursor from the previous page, at most 4,096 characters. Omit on the first request. |

Search filters combine with AND. Unknown keys, inactive fields and invalid formats are rejected. Inputs must fit 16 KiB. Results sort by FDC ID as text in ascending C collation, so 100 precedes 20.

### Output and a recorded example

Each completed run saves the same JSON envelope to the key-value store record **OUTPUT** and as **one item in the default Apify Dataset**: schema, qualification, ok, dataset, operation and response. Use the Output record or Operation results Dataset link. A search page is nested inside that one item's response.data; individual source records are not separate Dataset items. Dataset JSON export preserves the full envelope. CSV fields and nested-array expansion depend on the export options; the stored item remains one complete envelope.

Search response.data contains food summaries: fdc_id, description, food_category_id, publication_date and protein_g_per_100g. Detail response.data adds source fields and accepted measurements with nutrient definitions, units, provenance and quality flags. Decimal values are strings with twelve fractional places; precision does not imply measurement accuracy. Null means unknown, while zero remains zero. Measurements retain source units and the source_reported_per_100g_food basis without automatic summing or conversion. Repeated accepted food-nutrient pairs retain distinct measurement IDs and a repeated_food_nutrient flag. Metadata provides release, archive checksum, table counts and verification observations; dataset.record_count is the selected version, not search matches.

This paired dataset-input/output example was captured during private validation on October 20, 2026. Counts, versions and timestamps are historical examples, not a current freshness check. Its qualification is PRIVATE_UNQUALIFIED; the PPE path reports PPE_CANDIDATE, which identifies the execution mode rather than an Apify endorsement.

```json
{
  "schema": "waztap.actor-result/1",
  "qualification": "PRIVATE_UNQUALIFIED",
  "ok": true,
  "dataset": "usda.foundation",
  "operation": "dataset",
  "response": {
    "request_id": "67742e52-c036-4711-b40d-3f139fa1965d",
    "dataset": {
      "dataset_key": "usda.foundation",
      "source_url": "https://fdc.nal.usda.gov/download-datasets/",
      "license_label": "CC0_PUBLIC_DOMAIN",
      "version_id": "13ef3da8-a3ff-45e3-a119-389ed4c1b5a2",
      "record_count": 395,
      "table_counts": {
        "food": 395,
        "nutrient": 234,
        "food_nutrient": 16975
      },
      "source_release": "2026-04-30",
      "archive_sha256": "70457ee9d9342f43bda2010318c85f04210c689fdeb9cd2da4c513b0e8dbc655",
      "source_measurement_count": 17008,
      "excluded_measurement_count": 33,
      "version_captured_at": "2026-10-11T22:51:49.070Z",
      "published_at": "2026-10-11T22:53:49.940Z",
      "last_verified_snapshot_at": "2026-10-19T04:31:00.235Z",
      "verification_freshness": "fresh",
      "stale_after_seconds": 1209600
    },
    "refresh": {
      "last_attempt_at": "2026-10-19T04:30:30.113Z",
      "last_attempt_status": "unchanged",
      "expected_check_interval_seconds": 604800
    }
  }
}
```

### Pagination and freshness

Search returned_count equals the number of records in the page. A byte cap may return fewer records than requested. Copy next_cursor into a new search run with every filter and limit unchanged; null means no continuation. Each page is a separate operation and run. There is no automatic pagination or retry. An expired cursor requires a fresh search and reconciliation by record identifier. Do not reuse a cursor from a different account, dataset or filter set.

Read last_verified_snapshot_at, verification_freshness and source/version timestamps in each response. Verification freshness describes the age of Waztap's check. It does not promise upstream availability, a fixed source release schedule or an uptime SLA.

### Pricing

Price: **$0.002 per completed operation**, including a successful empty search. One operation means one metadata request, one bounded search page or one detail lookup. There is no per-row charge, Actor subscription, monthly included-call bundle or Waztap free-call quota. Confirm the final Pricing tab before use.

The approved pay-per-event configuration includes standard-run Apify platform usage in the event price, with only `waztap-completed-operation` and no separate start or dataset-item event. One event is requested after both output writes are acknowledged, including the one Dataset item. Subsequent storage access and retention follow Apify platform terms.

### Errors and retries

A failed run does not imply that no work occurred. OUTPUT is saved first, then the Dataset envelope, then the completed-operation charge is requested once. If either output write or charging has an uncertain outcome, inspect OUTPUT, the default Dataset and the run usage before trying again; do not assume a zero-cost failure or an automatic refund. Invalid/inactive input fields, unsupported IDs, expired cursors and excessive response sizes can fail a run. There is no automatic business-operation retry.

### Source and support

Source: [U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, 2026. fdc.nal.usda.gov](https://fdc.nal.usda.gov/). Foundation Foods source data are public domain under CC0. Waztap is independent and is not affiliated with or endorsed by USDA.

Requests are processed using Waztap infrastructure. No customer source credentials or arbitrary destination URL is an input. Do not submit passwords, API credentials, payment details or identity documents in inputs or support reports.

Contact: **support@waztap.com**, including privacy questions. The approved customer terms are Apify's Standard Actor Contract; the final native Contract section governs.

### Legal

Use of this API is subject to the Waztap Terms of Service (https://waztap.com/terms/), Acceptable Use Policy (https://waztap.com/acceptable-use/) and Privacy Policy (https://waztap.com/privacy/). Apify terms govern purchases and billing.

# Actor input Schema

## `operation` (type: `string`):

dataset (default): metadata; search: one bounded page; detail: one record. Omit inactive fields.

## `fdc_id` (type: `string`):

Required only for detail. Preserve as a string and omit for other operations.

## `query` (type: `object`):

Optional only for search. Default limit 20, maximum 50. Cursor remains opaque, unchanged query/limit is required; no automatic continuation.

## Actor input object example

```json
{
  "operation": "dataset"
}
```

# Actor output Schema

## `output` (type: `string`):

No description

## `results` (type: `string`):

One complete operation envelope per completed run; search records remain nested in response.data.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "operation": "dataset"
};

// Run the Actor and wait for it to finish
const run = await client.actor("waztap/usda-foundation-foods").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "operation": "dataset" }

# Run the Actor and wait for it to finish
run = client.actor("waztap/usda-foundation-foods").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "operation": "dataset"
}' |
apify call waztap/usda-foundation-foods --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,waztap/usda-foundation-foods"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cm1Z2Ur2GxhIeYTaN/builds/W5oPt9o7YiUaR0Ejj/openapi.json