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

# Salary Benchmark

> Benchmark a role's posted salary against the market and get percentiles, sample size, and where a proposed range sits

Queues a posted-salary benchmark for a role. Pass either a public job-posting URL or the role's attributes; the API resolves comparable postings from the last `days_ago` days and writes a report onto a [task](/docs/api-reference/tasks/get-task-status) you poll for the result.

<Warning>
  Requires authentication. Each request bills **1 unit** of `m_salary_benchmarks`: 3 per month on Free, 25 per month on API plans (then $0.25 each), 500 per month on Pro (then $0.05 each). See [plan allowances](/docs/api-reference/billing/usage-headers#what-each-plan-includes).
</Warning>

## Endpoint

```bash theme={null}
POST /v2/jobs/salary-benchmark
```

## Request Body

Either `public_url` or `job_title` is required. `public_url` takes precedence over the manual fields.

<ParamField body="public_url" type="string">
  Public job-posting URL to benchmark. When provided, the role attributes are extracted from the posting.
</ParamField>

<ParamField body="job_title" type="string">
  Primary job title when no URL is provided.
</ParamField>

<ParamField body="job_titles" type="string[]">
  Additional titles in the same occupational area to widen the comparison set.
</ParamField>

<ParamField body="yoe_range" type="object">
  Years-of-experience band, e.g. `{"min": 5, "max": 8}`. `yoe` is accepted as an alias.
</ParamField>

<ParamField body="description" type="string">
  Job description or notes used to expand the query.
</ParamField>

<ParamField body="salary_range" type="object">
  Proposed posted range to rank against the market, e.g. `{"min": 160000, "max": 190000, "currency": "USD", "period": "yearly"}`. When provided, the report includes where it sits as a percentile.
</ParamField>

<ParamField body="geo_locations" type="object[]">
  Locations to compare within, e.g. `[{"city": "Austin", "region": "Texas", "country": "United States"}]`. Country-only entries are accepted.
</ParamField>

<ParamField body="location_types" type="string[]">
  `Remote`, `Hybrid`, and/or `In-Person`.
</ParamField>

<ParamField body="industry" type="string[]">
  Industry filter — values from [Get Industries](/docs/api-reference/data/get-industries).
</ParamField>

<ParamField body="experience_levels" type="string[]">
  Experience levels to include.
</ParamField>

<ParamField body="days_ago" type="number" default="90">
  Lookback window in days (1–365).
</ParamField>

<ParamField body="notify" type="boolean" default="false">
  Send an email when the report is ready.
</ParamField>

## Response

Returns a task object (`id`, `type: "salary_benchmark"`, `state`, `progress`). Poll [`GET /v2/tasks/{task_id}`](/docs/api-reference/tasks/get-task-status) until `state` is `finished`; the report is in the task's `result`.

<ResponseField name="result.market.salary" type="object">
  Market distribution for comparable postings: `count` (sample size) and percentiles such as `p50` (median).
</ResponseField>

<ResponseField name="result.confidence" type="object">
  Confidence in the benchmark, including a letter `grade` driven by sample size and match quality.
</ResponseField>

<ResponseField name="result.proposed" type="object | null">
  Present when `salary_range` was supplied: the proposed `min`/`max` and the `percentile` the range sits at in the market distribution.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.hirebase.org/v2/jobs/salary-benchmark' \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "job_title": "Senior Software Engineer",
      "yoe_range": {"min": 5, "max": 10},
      "geo_locations": [{"country": "United States"}],
      "salary_range": {"min": 160000, "max": 190000, "currency": "USD", "period": "yearly"},
      "days_ago": 90
    }'
  ```

  ```python Python SDK theme={null}
  from hirebase import SalaryBenchmarkRequest

  task = client.jobs.salary_benchmark(SalaryBenchmarkRequest(
      job_title="Senior Software Engineer",
      yoe_range={"min": 5, "max": 10},
      geo_locations=[{"country": "United States"}],
      days_ago=90,
  ))
  success, report = client.tasks.poll(task, interval=5, timeout=900)
  market = report["market"]["salary"]
  print(market["count"], "postings, median", market["p50"], "confidence", report["confidence"]["grade"])
  ```
</CodeGroup>

<ResponseExample>
  ```json Task (queued) theme={null}
  {
    "id": "79a854ab-0543-478f-8bc5-f7261ce42fda",
    "type": "salary_benchmark",
    "state": "queued",
    "progress": 0
  }
  ```
</ResponseExample>

<Note>
  Reports are computed from posted salary ranges in Hirebase's job data, not from offers or survey data. Treat thin samples (low `count`, low confidence grade) as directional.
</Note>