BLS Time Series Observation Export

Refresh labor and inflation dashboards with official BLS time series observations. Supply Bureau of Labor Statistics series identifiers and an inclusive year range to export flat, typed rows with period labels, raw values, numeric values, source flags and footnotes. No registration key is required.

What does it do?

The Actor sends one bounded anonymous request to the official BLS public API v1. It exports one dataset row per unique series/year/period. It does not search for identifiers, infer units, calculate inflation changes or map FRED identifiers to BLS identifiers.

Who is it for?

• Economists refreshing CPI and unemployment charts.
• Workforce analysts tracking employment and earnings series.
• Data engineers loading official observations into recurring dashboards.

Why use this Actor?

Raw values remain available alongside nullable numeric values. Footnotes are preserved, including missing-data explanations and empty source footnote objects. A missing latest flag is null rather than a guessed statement that an observation is current. Stable series/year/period keys make downstream upserts straightforward.

Getting started

1. Choose official BLS series IDs from the BLS series report.
2. Enter one to 25 identifiers and a range of at most ten inclusive years.
3. Run the Actor and inspect the default dataset.
4. Download JSON or CSV, or connect the dataset to your pipeline.

The prefilled example requests CPI (CUUR0000SA0) and unemployment (LNS14000000) for 2024 with a 20-row demonstration cap. Raise maxItems to 1000 for the full set, normally 24 monthly observations. Omitted maxItems defaults to 1000. Data may be revised by BLS.

Inputs

Field	Default	Behavior
seriesIds	CPI and unemployment IDs above	1–25 alphanumeric identifiers; trimmed, uppercased, deduplicated
startYear	2024	Inclusive year, at least 1900
endYear	2024	Inclusive year, not in the future; ordered range, maximum ten years
maxItems	1000	Global output cap, 1–100000; no zero/unlimited mode

All series use the same years. Unknown input fields are rejected. Series are emitted in input order and each series follows source response order, typically newest first. A cap can exclude later series; choose a sufficiently large cap for full source coverage. This is not a guarantee that every requested year contains observations.

{"seriesIds":["CUUR0000SA0","LNS14000000"],"startYear":2024,"endYear":2024,"maxItems":20}

BLS time series output

Field	Meaning
seriesId	Official identifier
year	Calendar year as integer
period	Original BLS period code, such as M12 or M13
periodName	Original period label
rawValue	Unmodified value string
value	Finite number after comma removal, or null for missing/nonnumeric values
latest	BLS boolean flag, or null when not supplied
footnotes	Source code/text objects, including empty objects
sourceUrl	Official series page
scrapedAt	UTC normalization timestamp

Periods are not converted to calendar dates. M13 is an annual average, not a thirteenth month. Units and seasonal adjustment depend on the series identifier; the anonymous endpoint does not provide a full series catalog.

Output example

This CPI value was observed from the source during development; timestamp is illustrative.

{
  "seriesId":"CUUR0000SA0",
  "year":2024,
  "period":"M12",
  "periodName":"December",
  "rawValue":"315.605",
  "value":315.605,
  "latest":null,
  "footnotes":[{}],
  "sourceUrl":"https://data.bls.gov/timeseries/CUUR0000SA0",
  "scrapedAt":"2026-10-10T06:00:00.000Z"
}

How much does it cost to export BLS observations?

Pay-per-event pricing includes a $0.001 start fee per valid run and a per-observation item charge. No observation fee is charged for duplicates, rejected rows or failed fetches. Invalid input is rejected before the start fee. A valid request that subsequently fails can incur the start fee.

Apify Store spend tier	Per observation
FREE	$0.0017112
BRONZE	$0.001488
SILVER	$0.0011606
GOLD	$0.0008928
PLATINUM	$0.0008928
DIAMOND	$0.0008928

At BRONZE, 24 observations cost approximately $0.036712 including start; 100 cost $0.1498; 1000 cost $1.489. Spend tiers follow Apify's qualifying aggregate Store spend, not a private volume discount. These are Actor-event estimates, not guaranteed invoices; platform limits and applicable adjustments may affect totals.

Limits and failure behavior

Anonymous BLS access is restricted to 25 series and ten inclusive years per request. BLS also imposes daily request limits on the calling IP; concurrent customers share platform infrastructure, so availability is not guaranteed. There is no API-key input, proxy fallback or browser mode.

Network timeouts, HTTP 429 and temporary server errors get at most three total attempts with bounded backoff and a 30-second timeout per attempt. Stable HTTP failures, invalid JSON, source messages and malformed observations fail the run. No dataset rows are written until the complete response validates. A valid empty series array of observations emits no rows; BLS's explicit no-data messages are failures, not silent success. A failed run is not a complete export.

Integrations

Export the dataset to CSV for spreadsheets or consume JSON in a warehouse loader. Use (seriesId, year, period) as an upsert key and retain rawValue and footnotes for auditability. Schedule recurring Apify runs to refresh dashboards, then compare observations downstream. This Actor does not maintain a revision ledger or send alerts.

API usage

After the Actor becomes available to your account, use an Apify token through an environment variable. Never place credentials in Actor input.

curl -X POST "https://api.apify.com/v2/acts/automation-lab~bls-series-observation-export/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"seriesIds":["CUUR0000SA0"],"startYear":2024,"endYear":2024,"maxItems":1000}'

import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/bls-series-observation-export').call({
  seriesIds: ['CUUR0000SA0'], startYear: 2024, endYear: 2024, maxItems: 1000
});
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 100 });
console.log(items);

import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/bls-series-observation-export').call(run_input={
    'seriesIds': ['CUUR0000SA0'], 'startYear': 2024, 'endYear': 2024, 'maxItems': 1000
})
rows = client.dataset(run['defaultDatasetId']).list_items(limit=100).items
print(rows)

MCP use

For clients supporting the hosted Apify MCP service:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/bls-series-observation-export"

{"mcpServers":{"apify":{"url":"https://mcp.apify.com?tools=automation-lab/bls-series-observation-export"}}}

For Claude Desktop, Cursor and VS Code clients with remote MCP support, use the JSON URL configuration above through the client's MCP settings (VS Code may use servers instead of mcpServers). Authenticate using your client's supported Apify flow. Discover the actual tool names and schemas with scoped tools/list; actor selection also exposes run/data helpers, not exactly one tool. Example prompt: “Export 2024 CPI observations for CUUR0000SA0, then show the first 12 rows with period, rawValue and footnotes.”

Start an authorized run once and retain its run/storage IDs. IDs are metadata, not rows. If nonterminal, follow that same run with 2/4/8-second backoff capped at ten seconds, using a 120-second deadline and transport timeout longer than server wait. On timeout check the known run, never restart merely to poll. At deadline report pending; terminal failures are not successful exports.

After success, read bounded untransformed dataset pages with explicit fields, limit and offset. For example, admit at most 100 rows in pages of 20 and 64 KiB serialized UTF-8 content into model context, whichever comes first. Enforce byte bounds host-side; disclose truncation and continuation offset. If the client cannot intercept oversized responses, do not claim a hard byte guarantee. Full exports belong in downstream storage, not model context. No universal token-savings claim is made.

Legality, responsible use and affiliation

This is an independent data-export tool, not endorsed by or affiliated with the Bureau of Labor Statistics or Apify. It uses public statistical data and Apify's standard user terms. Respect BLS access limits and verify the source's methodology and revisions before making consequential decisions. It is not investment advice.

Data handling and diagnostics

Runtime extraction uses no AI or external paid data supplier. Requests send series identifiers and years to BLS. Public aggregate statistical observations are stored in the run's Apify dataset; no login, session cache or cross-run business state is maintained. Apify storage and logs follow your account retention settings and can be deleted through Console/API; this Actor does not impose an automatic dataset deletion period.

Failed operations send sanitized diagnostic input, exceptions and actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed; reports are retained for 30 days. Do not submit personal or confidential information in these statistical inputs.

FAQ and troubleshooting

Where do I find identifiers? Use the official BLS series report. This Actor accepts BLS IDs only; it does not map other providers' IDs.

Why is latest null? The API did not supply the flag for that observation. The Actor does not infer it.

Why are values missing? Some series/periods have no numeric observation. Inspect rawValue and footnotes. An explicit BLS no-data message fails the request so you can check identifiers and years.

Why did a request fail? Check series IDs, year limits and the run log. BLS may throttle a shared IP; retry later rather than splitting into many parallel runs.

Can it monitor changes? Apify scheduling refreshes the source snapshot; revision comparisons and alerts must be implemented downstream.

Related Actors and support

• FRED Economic Series Data Export: a separate economic data source using FRED identifiers.
• IMF World Economic Outlook Data Export: international economic projections.

There is no automatic identifier mapping between these products. For help, open an issue on the Actor's Apify page with series IDs, years and the run link; never include secrets.