US CPSC Recall & Safety Warning Monitor

Query and monitor official U.S. Consumer Product Safety Commission (CPSC) recalls and Product Safety Warnings. Get product names, models, hazards, injuries, remedies, manufacturers, retailers, images, and official source links as clean, automation-ready Dataset rows.

Use it for consumer-product compliance, supplier and product research, catalog screening, customer operations, and scheduled safety monitoring. The Actor keeps a stable source identity and idempotency key on every row, so a downstream workflow can trace an alert back to the CPSC notice and safely deduplicate retries.

Before you run

• For a one-off API call, use lookup or export. monitor is stateful and emits only new or changed rows after the monitor snapshot is established.
• Actor usage costs $0.004 per result, equivalent to $4 per 1,000 results, under Pay Per Event pricing. Runs with zero results have no result-item usage charge. See the Pricing tab for the current terms.
• Data is returned from CPSC at fetch time. This Actor does not provide a real-time freshness guarantee or an SLA for upstream publication delays.
• Start with one record type, a precise filter, and a small maxResults. Warning queries download and parse the complete official warning CSV even when maxResults is 1; a recall query may also download the complete official recall CSV if the REST service falls back. maxResults: 0 can therefore consume substantially more time and resources and is not an unlimited historical archive.
• Successful runs have a per-run Dataset. This Actor does not automatically rename it; retain the returned Dataset ID or name/copy important results before relying on your account's default retention policy.

What this Actor does

• Queries CPSC recalls and/or Product Safety Warnings.
• Filters by record type, exact recall or warning number, keyword, product name, manufacturer/importer, and inclusive publication windows.
• Normalizes HTML entities, source dates, nested product/hazard/remedy fields, URLs, and missing values into a predictable flat output contract.
• Supports lookup, export, and incremental monitor modes.
• Emits CURRENT rows for one-off queries, or ADDED/UPDATED rows for a recurring monitor.
• Publishes JSON rows to the run Dataset; Apify provides JSON, CSV, and Excel views of that same Dataset.

Why teams use it

CPSC data is valuable when it is easy to filter, compare, and route. This Actor turns two public machine-readable sources into a compact safety feed with source-level traceability, normalized dates, structured arrays, and change metadata—ready for a spreadsheet, alerting rule, data warehouse, or AI agent.

Common use cases:

• Find product recalls by hazard, manufacturer, product, or date.
• Track Product Safety Warnings alongside formal recalls.
• Export a historical year or quarter for research and compliance review.
• Schedule a defined query and receive only new or changed notices.

Data sources

Record type	Source	Role
recall	SaferProducts.gov Recall REST service	Primary recall source with structured fields and LastPublishDate
recall	CPSC recall listing CSV	Official recovery source if the REST service is unavailable or unusable
warning	CPSC Product Safety Warning CSV	Product Safety Warning records

The Actor uses the REST service for recall queries when possible and falls back to the official recall CSV after transient or unusable REST responses. The CSV does not include REST LastPublishDate, so fallback date filtering and change discovery use the available recall date and may not expose a later edit to an older notice as precisely as the REST path. Warning queries scan the official warning CSV and can be more expensive than an exact recall lookup.

The source is current at fetch time, but this Actor is not a complete historical archive. Use explicit date bounds for reproducible exports and retain important results in your own Dataset or downstream storage.

There is no row-level output field that identifies whether a recall row came from the REST service or the CSV fallback. The fallback is official, but its available dates and fields do not preserve all REST semantics.

Request and resource notes

• recall queries use the REST service when possible. If that request is unusable, the Actor downloads and parses the complete official recall CSV before applying local filters.
• warning queries download and parse the complete official warning CSV before applying local filters. An exact warning number still does not make the upstream download proportional to the number of returned rows.
• maxResults limits normalized records after source retrieval and filtering; it does not cap bytes downloaded or upstream work. In monitor mode, the final event count can be lower or zero after the state diff.
• maxResults: 0 removes the Actor-side result cap on the selected source, but it does not turn CPSC into an unlimited archive and can create a large Dataset.

Run modes

Mode	What it returns	State behavior
lookup	Matching current records as CURRENT	Does not read or change monitor state
export	A bounded current-source date-window result as CURRENT	Does not read or change monitor state
monitor	New and changed records as ADDED or UPDATED	Reads and updates the named Key-Value Store

Use lookup for a focused check, export for a defined report, and monitor for recurring change detection. The default mode is monitor; if publishedSince is omitted, it uses lookbackDays before today.

Quick start

Apify Console

1. Open the Actor and select Input.
2. Choose one or both recordTypes values: recall and warning.
3. Choose lookup, export, or monitor, then add a precise filter.
4. Keep maxResults small for the first run and click Start.
5. Inspect the Dataset or download JSON, CSV, or Excel from the Output tab.

Apify CLI

After installing and authenticating the Apify CLI:

apify call <ACTOR_ID> \
  --input '{"mode":"lookup","recordTypes":["recall"],"recallNumber":"26-716","maxResults":1}' \
  --output-dataset

<ACTOR_ID> can be the Actor ID or an authorized Actor name. A valid query with no matches completes successfully with zero Dataset items.

REST API

Start a run with a JSON request body:

curl -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "mode": "export",
    "recordTypes": ["recall"],
    "keyword": "lithium battery",
    "publishedSince": "2025-01-01",
    "publishedUntil": "2025-12-31",
    "maxResults": 100
  }' \
  "https://api.apify.com/v2/acts/<ACTOR_ID>/runs?waitForFinish=60"

Read the returned defaultDatasetId through the Dataset API:

GET https://api.apify.com/v2/datasets/<DATASET_ID>/items?format=json&clean=true
GET https://api.apify.com/v2/datasets/<DATASET_ID>/items?format=csv&clean=true&attachment=true
GET https://api.apify.com/v2/datasets/<DATASET_ID>/items?format=xlsx&clean=true&attachment=true

Use limit and offset for pagination. Keep $APIFY_TOKEN in an environment variable; never put it in Actor input, source code, logs, or Dataset records.

API run lifecycle

The POST request starts an Apify run; it does not return Dataset rows directly. If waitForFinish=60 returns a non-terminal status such as RUNNING, keep the returned runId and poll GET /v2/actor-runs/<RUN_ID> or use a Webhook. Read defaultDatasetId after the run reaches SUCCEEDED. A successful empty Dataset is valid; in monitor mode it can mean that no notice changed, not that CPSC had no matching notice.

Input API reference

The input is a JSON object. The ./.actor/input_schema.json is the machine-readable contract used by the Console and API.

Field	Type / default	Description
mode	enum, "monitor"	monitor, lookup, or export.
recordTypes	array; default recall, warning	One or both CPSC record classes. Allowed values are recall and warning; the array must not be empty.
keyword	string	Case-insensitive AND terms matched across title, description, products, models, hazards, manufacturers, retailers, and importers.
productName	string	Case-insensitive partial match against normalized product names.
manufacturer	string	Case-insensitive partial match across manufacturers and importers.
recallNumber	string	Exact normalized recall or warning number; punctuation and letter case are ignored for matching.
publishedSince	YYYY-MM-DD	Inclusive lower bound. The REST recall path sends it as LastPublishDateStart; CSV paths use their available record date.
publishedUntil	YYYY-MM-DD	Inclusive upper bound.
lookbackDays	integer, 7	Monitor-only lookback when publishedSince is omitted. Range: 0–3650.
maxResults	integer, 500	Maximum emitted rows. Range: 0–25000; 0 removes the Actor-side cap after retrieval/filtering, but does not avoid full CSV downloads or create an unlimited archive.
emitInitialSnapshot	boolean, true	In monitor, emit first-seen records as ADDED; set false to seed state without emitting the initial snapshot.
monitorId	string	Optional stable namespace for separate monitors sharing a state store.
stateStoreName	string, "us-cpsc-monitor-state"	Named Apify Key-Value Store used for monitor fingerprints.

Query behavior and validation

• Dates must be real calendar dates in YYYY-MM-DD; invalid dates such as 2026-02-30 are rejected.
• publishedSince cannot be after publishedUntil.
• Filtering is applied after source normalization and before maxResults.
• recordTypes controls which official sources are queried. A query containing both types can fetch a REST response plus one or more CSV files.
• maxResults is applied after normalization and filtering. It does not limit the warning CSV or recall-CSV download, and it does not prevent a REST fallback from scanning the complete recall CSV.
• A valid query with no matching records returns SUCCEEDED with an empty Dataset. Invalid input, malformed source payloads, or an unrecoverable upstream error fails the run with an explanatory message.

Example inputs

Monitor recalls and warnings by safety topic

{
  "mode": "monitor",
  "recordTypes": ["recall", "warning"],
  "keyword": "lithium battery",
  "lookbackDays": 14,
  "maxResults": 500,
  "monitorId": "battery-safety"
}

Look up one current recall

{
  "mode": "lookup",
  "recordTypes": ["recall"],
  "recallNumber": "26-716",
  "maxResults": 1
}

Export a historical CPSC window

{
  "mode": "export",
  "recordTypes": ["recall"],
  "publishedSince": "2015-01-01",
  "publishedUntil": "2015-12-31",
  "maxResults": 1000
}

Valid empty result and invalid input

An exact lookup for an unknown number is valid and returns an empty Dataset:

{
  "mode": "lookup",
  "recordTypes": ["recall"],
  "recallNumber": "not-a-real-recall",
  "maxResults": 1
}

An input such as {"publishedSince":"2026-02-30"} is rejected before the source is queried.

For abnormal upstream behavior, the Actor retries bounded transient failures such as 429, 5xx, network errors, and timeouts. Malformed source payloads and other unrecoverable responses fail the run with an explanatory error; they are not silently converted to an empty Dataset.

Output API reference

Each Dataset item is one normalized recall or warning. Array fields remain arrays; missing source values are represented by empty strings, empty arrays, or null dates according to the field contract.

Representative historical recall output

This trimmed example is based on a real CPSC recall record. Hash values and timestamps are placeholders for the values generated by the run; the complete row contains every field listed below.

{
  "source": "cpsc",
  "sourceRecordId": "recall:15123",
  "recordType": "recall",
  "recallNumber": "15123",
  "title": "Whistler Recalls Jump&Go Portable Jumpstart and Power Supply Units Due to Fire Hazard",
  "recallDate": "2015-04-28",
  "sourceUpdatedAt": "2015-04-28",
  "productNames": ["Portable jumpstart power supplies"],
  "unitsAffected": "About 10,400",
  "hazards": ["The jumpstart's lithium battery can overheat and cause the units to melt, catch fire and ignite nearby items, posing a fire hazard to consumers."],
  "remedies": ["Consumers should immediately stop using the recalled unit and contact Whistler for a free replacement."],
  "sourceUrl": "https://www.cpsc.gov/Recalls/2015/Whistler-Recalls-Jump-and-Go-Portable-Jumpstart-and-Power-Supply-Units",
  "changeType": "CURRENT",
  "changedFields": [],
  "detectedAt": "2026-09-02T00:00:00.000Z",
  "contentHash": "<sha256>",
  "idempotencyKey": "<sha256>"
}

For monitor, the same content fields are accompanied by ADDED or UPDATED; changedFields lists normalized fields that changed since the prior snapshot. CURRENT is used by lookup and export.

Identity and monitor metadata

Field	Type	Description
source	string	Always cpsc.
sourceRecordId	string	Stable identity, normally recall:<normalized-number> or warning:<normalized-number>.
recordType	string	recall or warning.
changeType	string	ADDED, UPDATED, or CURRENT.
changedFields	string[]	Normalized fields changed since the previous monitor snapshot; empty for ADDED and CURRENT.
detectedAt	ISO timestamp	Time this Actor produced the row.
contentHash	string	SHA-256 hash of the normalized source snapshot, excluding derived monitor metadata.
idempotencyKey	string	Stable key for monitor scope, source record, and content version. Use it to deduplicate retries.

Recall and warning fields

Field	Type	Description
recallNumber	string	Official CPSC recall or warning number.
title	string	Notice title or heading.
description	string	Product and notice description.
recallDate	string or null	Normalized notice date, YYYY-MM-DD when available.
sourceUpdatedAt	string or null	REST LastPublishDate when available; otherwise the available source date.
productNames	string[]	Product names.
productModels	string[]	Product models when supplied by the REST record.
unitsAffected	string	Reported units or quantities.
hazards	string[]	Hazard descriptions.
injuries	string[]	Injury or incident descriptions.
remedies	string[]	Consumer actions and remedy descriptions.
remedyOptions	string[]	Structured remedy options when supplied.
manufacturers	string[]	Manufacturers.
retailers	string[]	Retailers or sales channels.
importers	string[]	Importers.
distributors	string[]	Distributors.
manufacturerCountries	string[]	Reported manufacturing countries.
upcs	string[]	Product UPC values when supplied.
images	string[]	Official image URLs when supplied.
consumerContact	string	Consumer contact information when supplied.
soldAt	string	Reported sales location or channel text.
sourceUrl	string	Official CPSC notice or recall lookup URL.

Dataset and output links

The Actor pushes structured JSON rows only. Apify generates these views from the same Dataset:

• JSON: .../items?format=json&clean=true
• CSV: .../items?format=csv&clean=true&attachment=true
• Excel: .../items?format=xlsx&clean=true&attachment=true

Successful non-empty runs have their own Dataset ID. If long-term retention is required, name or copy the Dataset after the run; this Actor does not merge separate runs into a shared output Dataset. Dataset lifetime follows the retention rules of your Apify account and plan; do not treat an unnamed per-run Dataset as a permanent archive.

Monitoring and delivery semantics

In monitor mode:

1. Records are normalized and deduplicated by sourceRecordId.
2. The Actor compares normalized content with the snapshot in the named Key-Value Store.
3. New records become ADDED; changed records become UPDATED with changedFields.
4. Dataset delivery completes before the checkpoint is written.

This is safe at-least-once delivery. If Dataset delivery succeeds but the checkpoint write fails, a later run may emit the same event again; downstream consumers should deduplicate with idempotencyKey. Records absent from a later rolling source window are not emitted as REMOVED, because absence may reflect pagination, filtering, fallback-source coverage, or source-window behavior.

For scheduled monitoring, keep the same monitorId, stateStoreName, and query scope. The rolling date calculated from lookbackDays is not itself used to create a new state namespace every day.

The HTTP layer starts requests serially within one process, waits one second by default between request starts, retries transient network errors, 429, and 5xx responses with bounded exponential backoff and jitter, and honors Retry-After when supplied. These locks and limits are process-local; they do not provide account-wide rate limiting or cross-container exactly-once delivery.

Reliability and limitations

• Public CPSC endpoints can change fields, throttle requests, or enter maintenance windows. The Actor retries transient failures within a finite budget and uses the official recall CSV as a recovery source.
• The recall CSV cannot preserve REST LastPublishDate semantics.
• Warning CSV scans can be substantially larger than an exact recall lookup; use a precise filter, but remember that maxResults limits output after the scan rather than the download itself.
• CSV fallback rows do not carry a definitive row-level marker saying that the REST service was unavailable; preserve the normalized source fields and sourceUrl for audit context.
• The Actor reports what CPSC publishes. It does not independently verify product claims, injury reports, remedy effectiveness, or legal status.
• The Actor is not a product-specific legal or safety determination. Preserve sourceUrl and review the authoritative notice before acting.

Local development

Requirements: Node.js 20 or newer.

npm install
npm test
npm run build
apify validate-schema
npm run test:real

npm test uses deterministic fixtures and injected failures, including malformed payloads, 429/Retry-After, 5xx, rate limiting, state ordering, and delivery failure. The bounded real smoke script checks a current record, a historical record/date window, a valid empty result, and output identity/date fields; it is not an unbounded export.

Attribution

This Actor consumes public CPSC data. Review the current CPSC and SaferProducts.gov terms, availability, and usage guidance before operating at scale. Preserve sourceUrl and recallNumber when passing records downstream.