---
title: "Market-wide demand for a role"
method: GET
path: "/v1/markets/role-demand"
---

# Market-wide demand for a role

`GET /v1/markets/role-demand`

## Request

- Base URL: `https://api.reqbeat.com`
- URL: `https://api.reqbeat.com/v1/markets/role-demand`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Market-wide (no single-company scope) active-req demand series for
`function` / `geo` -- LinkedIn-excluded by construction
(ATS tenants plus public job boards and aggregators).

An unresolvable `function` -- anything that is neither a function name
nor a function taxonomy id -- is rejected with 422 instead of returning a
silently-empty result.

Requires the `read` scope.

## Query parameters

- `function` string, nullable: Function whose market demand to measure: its name as /v1/jobs/search serves it in `function_name`, e.g. 'Software & IT', or its taxonomy id as served in `function`, e.g. '54f81306-3000-5c4a-a088-dca4350b19ff'. A name covers every function id that serves it; an id matches that one id. Anything else is rejected with 422, which lists the names.
- `geo` string, nullable: Country name to restrict the demand measurement to, e.g. 'United States'. Matched against the geocoder's pinned list.
- `since` string, date-time, nullable: ISO-8601 timestamp lower bound on the demand window, e.g. '2026-01-01T00:00:00Z'. Omit for no lower bound.

## Headers

- `Idempotency-Key` string, nullable

## Response `200`

Successful Response

- RoleDemandResponse
  - `series` RoleDemandPoint[], required
    - `bucket` string, date-time, required
    - `active_reqs` integer, required
  - `as_of` string, date-time, required

## Other responses

- `401`: No API key was sent.
- `402`: The key is over its plan's rolling call quota, or the account is past its spend cap. `upgrade_url` and `purchase_url` are the ways out.
- `403`: The presented key is invalid or revoked, or (see `x-required-scope` on this operation) it does not carry the scope this operation requires.
- `422`: Validation Error
- `429`: Too many calls in the current 60-second window. The limit is per API key, set by the key's plan, and shared by every metered REST route and MCP tool; the shared demo key is limited per IP address instead. Wait `Retry-After` seconds and retry. The `RateLimit-*` headers are absent when `reason` is `key_throttled`.

---

[API](https://skmtc.dev/reqbeat/apis/reqbeat-api.md) · [All operations](https://skmtc.dev/reqbeat/apis/reqbeat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reqbeat/apis/reqbeat-api/revisions/4758e5957e8c?raw)