GET/v1/career/path

Analyse the skill-gap career path between two specific occupations

Return a detailed career-transition analysis between two specific occupations, answering 'what do I need to learn to move from A to B?' in one call. The response carries the list of shared skills (what the caller already has), the list of gap skills (what they need to develop), a composite similarity score, the expected wage change, and the target occupation's employment outlook. **When to use:** power a 'plan my next move' flow, generate a personal learning plan, or feed an LLM context with the exact skill deltas. **Inputs:** `from` (current SOC code) and `to` (target SOC code), both required query params. **Response shape:** an `ApiResponse[CareerPath]` with `shared_skills`, `gap_skills`, `similarity_score`, `wage_change_pct`, and target-side `outlook` data. Source: O*NET OnLine, BLS Employment Projections. Required scope: `skills:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
from	query	string	required	Source occupation SOC code (where you are now)
to	query	string	required	Target occupation SOC code (where you want to go)

Example request

curl

curl -X GET \
  "https://skills.wageapi.com/api/v1/career/path?from=%3Cfrom%3E&to=%3Cto%3E" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataCareerPathrequired

Career path recommendation with skill gap analysis.

target_socstringrequired

Target occupation SOC code

target_titlestringrequired

Target occupation title

similarity_scorenumberrequired

Overall skill match

min 0 · max 1

shared_skillsarray<string>optional

Skills you already have

array of string

string

gap_skillsarray<string>optional

Skills you need to develop

array of string

string

wage_change_pctanyoptional

Expected wage change

one of:

option 1:

number

option 2:

null

outlookanyoptional

Employment outlook for target occupation

one of:

option 1:

string

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

404Either `from` or `to` SOC code is not 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 →