API DOCUMENTATION / WHICH ROUTE
Which route should I use?
A decision guide for choosing between list, count, single-job, search, export and changes requests.
Start from what you need
| You want to | Use | Why |
|---|---|---|
| Know how many jobs match | GET /v1/jobs/count | Returns one number and no jobs. Run it before any large read. |
| Read one job you already have an ID for | GET /v1/jobs/{jobId} | Free. Add include=company or include=source_data when you need them. |
| Show or process a page of results | GET /v1/jobs | Filters in the query string, 50 jobs by default and up to 250, then follow next_cursor. |
| Send a long filter list or Boolean text | POST /v1/jobs/search | The same filters as a JSON body, so long lists do not hit URL limits. |
| Reuse an Elasticsearch query | POST /v1/jobs/search/es_dsl | Translates a bool query into the same filters. |
| Collect up to 100,000 matching jobs into files | POST /v1/jobs/exports | One request, then download gzip files. Easier than paging. |
| Collect every job ID for a filter | GET /v1/jobs?fields=job_id&limit=1000 | Id-only pages go up to 1,000 per page. |
| Keep a copy up to date | GET /v1/jobs/changes | Created, updated and expired events in order, so you never re-read the catalog. |
| Find a company or list its jobs | /v1/companies, /v1/companies/search, /v1/companies/{id}/jobs | Company IDs are stable and merged IDs redirect. |
| Check your own usage | GET /v1/usage/requests, /v1/usage/analytics | Your request ledger and daily totals. |
| Give an AI agent job search | The MCP server | Ready-made tools. See MCP tools. |
Pick by size
| Jobs you need | Best route |
|---|---|
| A few, to show a user | One GET /v1/jobs call |
| Up to a few thousand | GET /v1/jobs with a cursor loop |
| Up to 100,000 | One export |
| More than 100,000 | Split the filter (by country, state, source or posted date) and run one export at a time, or load with GET /v1/jobs and keep up with changes |
| Everything, kept fresh | Initial load, then the changes feed |
Count first when you are unsure. GET /v1/jobs/count is cheap and tells you which row of this table you are in.
Pick a search style
| Situation | Use |
|---|---|
| Simple words in a title or description | q, title or description |
| Several words in any order, exclusions or groups | title_advanced or description_advanced |
| Exact structure from an existing Elasticsearch client | POST /v1/jobs/search/es_dsl |
| A place | country, state, city, msa or location. See search and location filters |
| Remote work | work_arrangement=remote, not a place name |
The query language page has the exact syntax.
What each route costs
Pricing is per request. Reading a single job is free. Filtered lists and counts are billed at the list price and keyword searches at the search price, after your free allowance of up to 1,000,000 jobs a day. The numbers are on the pricing page, and rate limits explains how the allowance and the per-minute limits work.