GET/v1/occupations

List all O*NET occupations (paginated, with filters)

Return a paginated list of every occupation in the O*NET Content Model (~900 US SOC occupations). Use this endpoint to browse the taxonomy, build drop-down widgets, or pre-filter by preparation level, bright outlook, or green economy relevance before drilling into detail. For keyword search use `GET /v1/occupations/search` instead. **Filters:** - `job_zone` (1-5) — O*NET preparation level. 1 = little or no preparation, 5 = extensive education and experience required. - `bright_outlook` — restrict to BLS Bright Outlook occupations (fast growing or large number of openings). - `green` — restrict to green-economy occupations identified by O*NET. **Pagination:** `page` / `page_size` (defaults 1 / 20, max 100). **Response shape:** `ApiResponse[PaginatedData[OccupationSummary]]` — each summary has `soc_code`, `title`, `job_zone`, `bright_outlook`, `green_occupation`. Source: O*NET OnLine (USDOL/ETA). Required scope: `skills:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
page	query	integer	optional	Page number (1-based)
page_size	query	integer	optional	Items per page (max 100)
job_zone	query	any	optional	Filter by preparation level (1=little, 5=extensive)
bright_outlook	query	any	optional	Filter to bright outlook occupations only
green	query	any	optional	Filter to green economy occupations only

Example request

curl

curl -X GET \
  "https://skills.wageapi.com/api/v1/occupations?page=1&page_size=20&job_zone=%3Cjob_zone%3E&bright_outlook=%3Cbright_outlook%3E&green=%3Cgreen%3E" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataPaginatedData_OccupationSummary_required

itemsarray<OccupationSummary>required

array of OccupationSummary

soc_codestringrequired

Standard Occupational Classification code (e.g. 15-1252.00)

titlestringrequired

Official occupation title

job_zoneanyoptional

Preparation level 1-5 (1=little, 5=extensive)

one of:

option 1:

integer

option 2:

null

bright_outlookbooleanoptional

True if projected to grow much faster than average

default false

green_occupationbooleanoptional

True if related to green economy

default false

totalintegerrequired

Total number of matching records

pageintegerrequired

Current page number (1-based)

page_sizeintegerrequired

Items per page

pagesintegerrequired

Total number of pages

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

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 →