GET/v1/occupations/{soc_code}/projection

Get the latest BLS employment projection (10-year outlook) for an occupation

Return the most recent BLS Employment Projection for a single occupation — a 10-year forward-looking outlook published annually by the BLS. Use this endpoint to render 'is this a growing job?' widgets or feed career-recommendation engines. **Fields:** `base_employment`, `projected_employment`, `percent_change`, `annual_job_openings`, and an `outlook` category (`bright`, `average`, or `declining`). **Missing data:** not every O*NET occupation has a published BLS projection (some newer occupations ship without one). In that case the response data will be `null` — this is not an error and the HTTP status will still be 200. **Response shape:** `ApiResponse[ProjectionData | None]`. Source: BLS Employment Projections program. Required scope: `skills:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
soc_code	path	string	required

Example request

curl

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

Responses

200Successful Response

dataanyrequired

one of:

option 1:

year_baseintegerrequired

Base year for projection

year_projectedintegerrequired

Target projection year

employment_baseanyoptional

Employment in base year (thousands)

one of:

option 1:

integer

option 2:

null

employment_projectedanyoptional

Projected employment (thousands)

one of:

option 1:

integer

option 2:

null

change_pctanyoptional

Projected percent change in employment

one of:

option 1:

number

option 2:

null

openings_annualanyoptional

Projected annual job openings (thousands)

one of:

option 1:

integer

option 2:

null

outlookanyoptional

bright | average | declining

one of:

option 1:

string

option 2:

null

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 →