GET/v1/occupations/{soc_code}

Get the full profile for a single occupation (skills + tasks + wages + outlook)

Return a complete O*NET occupation profile in a single request, including the full skill list (with per-skill importance and proficiency level scores), task statements, national BLS wage data, and the latest BLS employment projection. Use this endpoint when a caller wants comprehensive information about one occupation — for example to render a job-profile page or feed an LLM context window in one shot. **Path parameter:** `soc_code` is the O*NET extended SOC code (e.g. `15-1252.00` for Software Developers, `29-1141.00` for Registered Nurses). **Response shape:** an `OccupationDetail` containing metadata (`title`, `description`, `job_zone`, `bright_outlook`, `green_occupation`), plus optional nested blocks for `skills`, `tasks`, `wages` (national figures only — use `GET /v1/occupations/{soc_code}/wages` for all areas), and `projection`. **Tip:** the heaviest queries join across skills / tasks / wages / projections. If the caller only needs one of those, prefer the dedicated sub-endpoint for a cheaper response. Source: O*NET OnLine, BLS OES, BLS Employment Projections. 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" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataOccupationDetailrequired

Full occupation profile with all available data.

soc_codestringrequired

Standard Occupational Classification code

titlestringrequired

Official occupation title

descriptionanyoptional

What workers in this occupation typically do

one of:

option 1:

string

option 2:

null

job_zoneanyoptional

Preparation level 1-5

one of:

option 1:

integer

option 2:

null

bright_outlookbooleanoptional

Projected to grow much faster than average

default false

green_occupationbooleanoptional

Related to green economy

default false

skillsanyoptional

Skills with importance/level scores

one of:

option 1:

array of OccupationSkillDetail

skill_idstringrequired

O*NET skill identifier

namestringrequired

Skill name

categorystringrequired

knowledge | skill | ability

importancenumberrequired

How important this skill is (0.00-1.00)

min 0 · max 1

levelnumberrequired

Required proficiency level (0.00-1.00)

min 0 · max 1

option 2:

null

tasksanyoptional

Task statements

one of:

option 1:

array of OccupationTaskDetail

task_idstringrequired

O*NET task identifier

descriptionstringrequired

What the task involves

importanceanyoptional

Normalized importance score 0.00-1.00

one of:

option 1:

number

option 2:

null

option 2:

null

wagesanyoptional

National wage data

one of:

option 1:

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

option 2:

null

projectionanyoptional

Employment outlook

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 →