Tools (5)

get_series
get_latest
get_multiple_series
get_popular_series
report_feedback

get_series

Get time series data from the Bureau of Labor Statistics.

BLS publishes official US government data on employment, unemployment,
consumer prices (CPI), producer prices (PPI), productivity, wages, and
occupational statistics. This tool fetches observations when you know
the series ID.

Common series IDs:
- LNS14000000 — Unemployment Rate (monthly, seasonally adjusted)
- CES0000000001 — Total Nonfarm Payrolls (monthly, seasonally adjusted)
- CUUR0000SA0 — CPI-U All Items (monthly, not seasonally adjusted)
- CUSR0000SA0 — CPI-U All Items (monthly, seasonally adjusted)
- CUUR0000SA0L1E — CPI-U Core (less food and energy)
- WPU00000000 — PPI All Commodities
- CES0500000003 — Average Hourly Earnings, Total Private
- PRS85006092 — Nonfarm Business Labor Productivity

Use get_popular_series() to browse curated series by category, or check
https://data.bls.gov/dataQuery/find for the full BLS series catalog.

Args:
series_id: BLS series identifier (e.g. "CUUR0000SA0", "LNS14000000").
start_year: Start year (YYYY). If omitted, BLS returns the latest 3 years
(10 years without API key).
end_year: End year (YYYY). If omitted, fetches to the latest available.
calculations: Include net changes and percent changes (1, 3, 6, 12 month).
Requires API key.
annual_averages: Include annual average values alongside monthly data.
Requires API key.

Returns:
series_id, observation_count, and observations list with year, period,
period_name, value, and optional latest flag and calculations.

Parameter	Type	Required	Description
`series_id`	`string`	required	BLS series identifier (e.g. "CUUR0000SA0", "LNS14000000").
`start_year`	`any`	optional	Start year (YYYY). If omitted, BLS returns the latest 3 years (10 years without API key).
`end_year`	`any`	optional	End year (YYYY). If omitted, fetches to the latest available.
`calculations`	`boolean`	optional	Include net changes and percent changes (1, 3, 6, 12 month). Requires API key. (default: false)
`annual_averages`	`boolean`	optional	Include annual average values alongside monthly data. Requires API key. (default: false)

Request Body

{
  "series_id": "example"
}

get_latest

Get the most recent observation for a BLS series.

Convenience wrapper that fetches a series and returns only the latest
data point. Useful for quick lookups like "what is the current
unemployment rate?" or "what is the latest CPI reading?".

Args:
series_id: BLS series identifier (e.g. "LNS14000000" for unemployment rate).

Returns:
series_id, year, period, period_name, and value of the most recent observation.

Parameter	Type	Required	Description
`series_id`	`string`	required	BLS series identifier (e.g. "LNS14000000" for unemployment rate).

Request Body

{
  "series_id": "example"
}

get_multiple_series

Fetch multiple BLS series in a single request.

Retrieves data for up to 50 series at once (25 without API key).
Useful for comparing indicators side by side, e.g. unemployment rate
alongside CPI and nonfarm payrolls.

Args:
series_ids: List of BLS series IDs (max 50 with key, 25 without).
start_year: Start year (YYYY).
end_year: End year (YYYY).

Returns:
count and list of series, each with series_id, observation_count, and observations.

Parameter	Type	Required	Description
`series_ids`	`list[string]`	required	List of BLS series IDs (max 50 with key, 25 without).
`start_year`	`any`	optional	Start year (YYYY).
`end_year`	`any`	optional	End year (YYYY).

Request Body

{
  "series_ids": [
    "example"
  ]
}

get_popular_series

Browse curated popular BLS series organized by category.

Returns well-known, commonly-referenced BLS series IDs with titles.
Use this when you need to find the right series ID for employment,
prices, productivity, or wages data.

Available categories:
- employment — unemployment rate, nonfarm payrolls, labor force, JOLTS
- prices — CPI-U (all items, core, food, shelter, gasoline), PPI
- productivity — labor productivity, unit labor costs, real compensation
- wages — employment cost index, average hourly earnings, median weekly earnings

Args:
category: Filter to a specific category. If omitted, returns all categories.

Returns:
If category specified: category name and list of series (series_id, title).
If omitted: list of category names and all series grouped by category.

Parameter	Type	Required	Description
`category`	`any`	optional	Filter to a specific category. If omitted, returns all categories.

Request Body

{
  "query": "example"
}

report_feedback

Report a bug, feature request, or general feedback for this data source.

Use this when something doesn't work as expected, when you'd like
a new feature, or when you have suggestions for improvement.

Args:
feedback: Describe the issue or suggestion.
feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	`string`	required
`feedback_type`	`string`	optional	(default: "general")

Request Body

{
  "feedback": "example"
}

Quick Start

Shell

curl -X POST "https://context.gnist.ai/rest/bls/get_series" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"series_id": "example"}'

Python

import httpx

resp = httpx.post(
    "https://context.gnist.ai/rest/bls/get_series",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={
  "series_id": "example"
},
)
print(resp.json())