GET/v1/occupations/{soc_code}/wages

Get BLS OES wage data for an occupation across every geographic area

Return BLS Occupational Employment and Wage Statistics (OES) data for a single occupation, covering median, mean, and percentile (p10, p25, p75, p90) wages in every geographic area where the BLS publishes a figure. Each row also carries total employment for the area. **When to use:** compare wages across metros for the same job, feed a relocation calculator, or render a wage-map widget. **Filters:** - `area_code` — narrow the response to a single BLS area. Use `0000000` for the US national figure, or a metro-specific code (discover via `GET /v1/occupations/{soc_code}` which returns the national row). **Response shape:** `ApiResponse[list[WageData]]` with one row per area. **Related:** for a salary benchmark keyed on a job title and metro area instead of a SOC code, see the salary-api `GET /v1/salary` endpoint. Source: BLS OES annual releases. Required scope: `skills:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
soc_code	path	string	required
area_code	query	any	optional	BLS area code (e.g. '0000000' for national)

Example request

curl

curl -X GET \
  "https://skills.wageapi.com/api/v1/occupations/%3Csoc_code%3E/wages?area_code=%3Carea_code%3E" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataarray<WageData>required

array of WageData

area_codestringrequired

BLS area code (e.g. 0000000 for national)

yearintegerrequired

Data year

mediananyoptional

Annual median wage in USD

one of:

option 1:

integer

option 2:

null

meananyoptional

Annual mean wage in USD

one of:

option 1:

integer

option 2:

null

pct10anyoptional

10th percentile annual wage in USD

one of:

option 1:

integer

option 2:

null

pct25anyoptional

25th percentile annual wage in USD

one of:

option 1:

integer

option 2:

null

pct75anyoptional

75th percentile annual wage in USD

one of:

option 1:

integer

option 2:

null

pct90anyoptional

90th percentile annual wage in USD

one of:

option 1:

integer

option 2:

null

hourly_mediananyoptional

Hourly median wage in USD

one of:

option 1:

number

option 2:

null

hourly_meananyoptional

Hourly mean wage in USD

one of:

option 1:

number

option 2:

null

total_employmentanyoptional

Total employment in area

one of:

option 1:

integer

option 2:

null

metadataMetadataSchemarequired

sourcesarray<SourceSchema>optional

array of SourceSchema

namestringrequired

Data source name (e.g. O*NET, BLS OES)

urlanyoptional

URL to the source

one of:

option 1:

string

option 2:

null

request_idstringrequired

Unique request identifier

rate_limitanyoptional

one of:

option 1:

limitintegerrequired

Maximum requests per day for current tier

remainingintegerrequired

Requests remaining today

resetstringrequired

UTC timestamp when limit resets

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

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

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

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

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

404The SOC code does not exist in the loaded O*NET taxonomy.

errorErrorDetailrequired

codestringrequired

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

messagestringrequired

Human-readable error message

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

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, unknown category, etc.).

errorErrorDetailrequired

codestringrequired

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

messagestringrequired

Human-readable error message

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

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

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

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

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

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 →