> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Salaries API

> Jobs API salaries: observed min, max, average, and median pay in one currency and interval. Optional role filter. GET /v1/salaries.



## OpenAPI

````yaml jobs-api/openapi.json GET /v1/salaries
openapi: 3.0.3
info:
  title: Clair Job Search API
  version: 1.0.0
  description: >-
    Search normalized active jobs and analyze hiring demand by role, skill,
    company, country, workplace type, and observed salary. Includes source
    provenance, freshness, and canonical taxonomies. Coverage:
    https://clair.im/resources/datasets/active-jobs
servers:
  - url: https://api.clair.im
    description: 'Clair origin. Authenticate with Authorization: Bearer <key>.'
security:
  - bearerAuth: []
paths:
  /v1/salaries:
    get:
      summary: Observed salary range
      description: >-
        Returns minimum, maximum, average, and median pay for one currency and
        interval across canonical active postings. Defaults to USD yearly. Does
        not convert currencies or mix hourly with yearly figures. Optionally
        filter by role, skill, country, workplace type, or seniority.
      operationId: getSalaries
      parameters:
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/WorkplaceType'
        - $ref: '#/components/parameters/Seniority'
        - $ref: '#/components/parameters/Role'
        - $ref: '#/components/parameters/Skill'
        - $ref: '#/components/parameters/IntelligenceCurrency'
        - $ref: '#/components/parameters/IntelligenceSalaryInterval'
      responses:
        '200':
          description: Observed compensation statistics for the selected market slice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalariesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Country:
      name: country
      in: query
      description: Optional ISO 3166-1 alpha-2 country filter.
      schema:
        type: string
        pattern: ^[A-Za-z]{2}$
      example: US
    WorkplaceType:
      name: workplace_type
      in: query
      description: Optional normalized workplace filter.
      schema:
        type: string
        enum:
          - remote
          - hybrid
          - onsite
    Seniority:
      name: seniority
      in: query
      description: Optional normalized seniority filter.
      schema:
        type: string
        enum:
          - intern
          - entry
          - mid
          - senior
          - staff
          - principal
          - executive
    Role:
      name: role
      in: query
      description: Canonical role ID or name from `/v1/taxonomy/roles`.
      schema:
        type: string
        minLength: 1
        maxLength: 160
      example: data-engineer
    Skill:
      name: skill
      in: query
      description: Canonical skill ID or name from `/v1/taxonomy/skills`.
      schema:
        type: string
        minLength: 1
        maxLength: 160
      example: Python
    IntelligenceCurrency:
      name: currency
      in: query
      description: >-
        ISO 4217 currency for the salary slice. Defaults to USD. Currencies are
        never converted.
      schema:
        type: string
        pattern: ^[A-Za-z]{3}$
        default: USD
      example: USD
    IntelligenceSalaryInterval:
      name: salary_interval
      in: query
      description: >-
        Pay interval for the salary slice. Defaults to year. Hourly and yearly
        figures are never mixed.
      schema:
        type: string
        enum:
          - year
          - hour
          - month
          - week
          - day
        default: year
  schemas:
    SalariesResponse:
      allOf:
        - $ref: '#/components/schemas/IntelligenceEnvelope'
        - type: object
          required:
            - currency
            - interval
            - postings_analyzed
            - salary_postings
            - min
            - max
            - average
            - median
          properties:
            currency:
              type: string
            interval:
              type: string
              enum:
                - year
                - hour
                - month
                - week
                - day
            postings_analyzed:
              type: integer
            salary_postings:
              type: integer
            min:
              type: number
              nullable: true
            max:
              type: number
              nullable: true
            average:
              type: number
              nullable: true
            median:
              type: number
              nullable: true
    IntelligenceEnvelope:
      type: object
      required:
        - updated_at
        - filters
      properties:
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: Latest verification time represented by the aggregation.
        filters:
          type: object
          additionalProperties:
            type: string
          description: Normalized filters applied to the aggregation.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Stable machine-readable code. Branch on this value.
          example: bad_cursor
        detail:
          description: >-
            Human-readable detail. Validation errors return an array; typed
            failures return a string. Do not parse this field.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
  responses:
    BadRequest:
      description: Invalid filter or unknown canonical role or skill.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid Bearer authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Wallet empty or account rate limit exceeded.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Clair dashboard key. Create keys at https://clair.im/dashboard/api-keys.

````