Skip to main content
POST
Salary Benchmark
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 you poll for the result. By default the sample includes both jobs that are open now and jobs that closed inside the window, which gives deeper samples and a month-by-month trend. Set include_expired: false to benchmark only against jobs that are open now.
Requires authentication. Each request bills 1 unit of m_salary_benchmarks: 3 per month on Free, 25 per month on API plans (then 0.25each),500permonthonPro(then0.25 each), 500 per month on Pro (then 0.05 each). A benchmark whose task fails is refunded. See plan allowances.

Endpoint

Request Body

Either public_url or job_title is required. public_url takes precedence over the manual fields.
string
Public job-posting URL to benchmark. When provided, the role attributes are extracted from the posting.
string
Primary job title when no URL is provided.
string[]
Additional titles in the same occupational area to widen the comparison set.
object
Years-of-experience band, e.g. {"min": 5, "max": 8}. yoe is accepted as an alias.
string
Job description or notes used to expand the query.
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. Hourly, weekly, and monthly ranges are annualized before ranking.
object[]
Locations to compare within, e.g. [{"city": "Austin", "region": "Texas", "country": "United States"}]. Country-only entries are accepted.
string[]
Remote, Hybrid, and/or In-Person.
string[]
Industry filter — values from Get Industries.
string[]
Narrower sub-industry filter, e.g. ["Fintech"], from Get Subindustries. When set, it replaces industry.
string[]
Hint used to pick a years-of-experience band when yoe_range is not set. Not a filter; send yoe_range for a precise band.
number
default:"90"
Lookback window in days (1–365). Open jobs must have been posted inside it; closed jobs must have closed inside it.
boolean
default:"true"
Include jobs that closed inside the window. false benchmarks only against jobs that are open now.
boolean
default:"false"
Send an email when the report is ready.

Response

Returns a task object (id, type: "salary_benchmark", state, progress). Poll GET /v2/tasks/{task_id} until state is finished; the report is in the task’s result.
object
Annual pay distribution for comparable postings: count (sample size), percentiles such as p50 (median), and currency. Pay is in the market’s currency (USD in the US, GBP in the UK, …); hourly, weekly, and monthly postings are annualized.
object
Typical posted floor and ceiling: percentiles of the annual min and max of each posting’s range.
object[]
Percentiles for jobs open now (live) and jobs that closed inside the window (expired).
object[]
Percentiles by posting month (YYYY-MM). Closed jobs are grouped by the month they were posted, which can be before the window.
object
Confidence in the benchmark, including a letter grade driven by sample size and match quality.
object | null
Present when salary_range was supplied: the proposed annual min/max, the percentile the range sits at in the market distribution, and a verdict. If salary_range.currency differs from the market currency, percentile is null and error explains why.
object[]
A sample of up to 25 source postings spread across the distribution (title, company, location, posted range). result.listings_total is the full sample size.

Example

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.