GET/v1/jobs/search

Search for job titles and SOC occupations by keyword

Fuzzy search across 1,400+ US Standard Occupational Classification (SOC) occupations by job title. Use this endpoint as the *first step* when a caller only knows a free-form job title (e.g. 'data engineer', 'nurse', 'accountant') and needs to discover the canonical SOC code before querying salary or trend data. **Matching strategy:** a 3-tier pipeline running in order until a match is found — (1) exact alias lookup in the O*NET alternate titles table, (2) PostgreSQL `pg_trgm` trigram similarity against occupation titles, (3) a final `ILIKE '%term%'` fallback. Returns an empty list only if all three tiers miss. **Response:** each result includes the SOC code, canonical title, description, top skills, required education level, and BLS job-outlook signal (Growing, Declining, Stable). **Typical downstream call:** feed the `soc_code` or `title` from the top result into `GET /v1/salary?job_title=...` or `GET /v1/trends`. Source: O*NET Web Services by USDOL/ETA + BLS SOC taxonomy. Required scope: `salary:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
query	query	string	required	Job title to search for, e.g. 'data engineer', 'nurse', 'accountant'
limit	query	integer	optional	Maximum number of results to return (1-50)

Example request

curl

curl -X GET \
  "https://salary.wageapi.com/api/v1/jobs/search?query=%3Cquery%3E&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

resultsarray<JobResult>required

array of JobResult

soc_codestringrequired

titlestringrequired

descriptionanyrequired

one of:

option 1:

string

option 2:

null

skillsarray<string>optional

default []

array of string

string

educationanyrequired

one of:

option 1:

string

option 2:

null

job_outlookanyrequired

one of:

option 1:

string

option 2:

null

related_codesarray<string>optional

default []

array of string

string

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

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

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

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

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 JSON shape, missing required fields, etc.).

errorErrorDetailrequired

codestringrequired

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

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

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

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

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

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

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 →