GET/v1/prices/us/items/{item_code}

Get the latest price of a specific item across every US metro area

Return the latest price of a single consumer item across every US metropolitan area where BLS has published a recent observation. Use this endpoint to power single-item comparison widgets ('where is gasoline cheapest?') or to feed cross-city cost calculators. **Path parameter:** `item_code` is a BLS Consumer Price Index average price series ID. Examples: `APU0000708111` (eggs, grade A, large, per dozen), `APU0000711211` (bread, white, per lb), `APU000074714` (gasoline, unleaded regular, per gallon). **Response shape:** an `ItemDetail` with the item code, description, unit, and a list of `(area_code, area_name, latest_price, price_date)` rows covering every metro with data. **Note:** not every item is surveyed in every metro. Rows without a recent observation are omitted, not returned as null. Source: BLS Consumer Price Index average price surveys. Required scope: `costapi:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
item_code	path	string	required	BLS average-price item code, e.g. APU0000708111 (eggs)

Example request

curl

curl -X GET \
  "https://col.wageapi.com/api/v1/prices/us/items/%3Citem_code%3E" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataItemDetailrequired

item_codestringrequired

item_nameanyoptional

one of:

option 1:

string

option 2:

null

areasarray<ItemAreaPrice>optional

array of ItemAreaPrice

area_codestringrequired

area_nameanyoptional

one of:

option 1:

string

option 2:

null

periodstring (date)required

priceanyoptional

one of:

option 1:

number

option 2:

null

currencystringoptional

default "USD"

metadataMetadataSchemarequired

sourcesarray<SourceSchema>optional

array of SourceSchema

namestringrequired

Data source name (e.g., 'BLS', 'OECD', 'Eurostat')

datasetstringrequired

Specific dataset identifier

urlanyoptional

URL to the source dataset

one of:

option 1:

string

option 2:

null

last_updatedanyoptional

When this data was last refreshed

one of:

option 1:

string (date-time)

option 2:

null

request_idstringrequired

Unique request identifier

rate_limitanyoptional

one of:

option 1:

remainingintegerrequired

Remaining requests today

daily_limitintegerrequired

Total daily request limit

reset_atstring (date-time)required

When the rate limit resets

option 2:

null

paginationanyoptional

one of:

option 1:

pageintegerrequired

page_sizeintegerrequired

totalintegerrequired

total_pagesintegerrequired

option 2:

null

data_vintageanyoptional

Data freshness (e.g., 'CPI data from February 2026')

one of:

option 1:

string

option 2:

null

methodology_notesanyoptional

Methodology notes (e.g., 'CPI rebased to 2020=100')

one of:

option 1:

string

option 2:

null

401Missing or invalid API key.

errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

403API key lacks the required scope for this endpoint.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

404Unrecognised item code or no price data loaded.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

422Request validation failed (bad query params, unresolvable country, etc.).

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

429Daily rate limit exceeded for this API key.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

500Unexpected server error. Includes a request_id for support.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

Try this endpoint

Create a free Aethar account and generate an API key in 2 minutes.

Create free account →