jobdata API Documentation

Endpoint Documentation

To access an endpoint without the hourly rate limit, you need to include the Authorization header with the value Api-Key YOUR_API_KEY, where YOUR_API_KEY should be replaced with your actual API key. For quick testing you can add your API key via the api_key GET parameter to every request instead, but make sure you don't leave traces of it in your browser history or simply create a new API key afterwards.

You can generate an API key from your dashboard if you're a subscribed customer. If you haven't subscribed yet please check our pricing page and hit Subscribe now on the plan that best suits your needs.

Currently there are up to five plans available for subscription:

access lite: Includes all features of our base access plan but is limited to a latest-jobs feed for the past 90 days and does not include date range, ID range or age-range slicing filters.
access: Our normal base plan with access to all job posts in the database and daily job data feed.
access pro: Adds full-text search with access to expired jobs info and full company data.
access pro+: Adds embeddings for every job post and basic vector search capabilities on top of all pro features.
access ultra: All of the above plus complete weekly database dumps in CSV and Parquet formats.

When a feature or endpoint requires the pro, pro+ or ultra plan it will be indicated by showing an access pro, access pro+ or access ultra badge next to it.

For the /api/jobs/ endpoint, requests default to a max_age=90 filter internally when no explicit max_age is provided. You can disable this behavior on non-lite plans by setting max_age=off, max_age=null or max_age=0.

Overview

The following is a comprehensive list of documentation pages for every API endpoint:

Job Regions API Endpoint Documentation Job data
A list of regions available for job search.
Job Countries API Endpoint Documentation Job data
A list of countries available for job search.
Job States API Endpoint Documentation Job data
A list of states available for job search.
Job Cities API Endpoint Documentation Job data
A list of cities available for job search.
Jobs API Endpoint Documentation Job data
Fetching job listings with advanced filters.
Job Types API Endpoint Documentation Job data
A list of job types available for job search.
Jobs Deleted API Endpoint Documentation
Track permanently deleted job postings with a durable sequence-based synchronization feed.
Vector Embeddings and Search API Documentation Job data access pro+
Enhance job searches with semantic understanding through vector embeddings.
Date, ID, and Age Slicing Parameters Documentation Job data
Slice smarter, sync faster: precise dataset windows for the /api/jobs/ endpoint
Jobs Expired API Endpoint Documentation Job data access pro
Tracking the lifecycle of job postings.
Full-Text Search on Job Descriptions Job data access pro
Leverage precise text queries to navigate millions of job descriptions.
Multi-value Parameters Documentation Job data
Narrow down your job and company data queries or get even more flexible with our multi-value parameters.
Currency Rates API Endpoint Documentation Job data
Accessing historical and current foreign exchange rates for salary conversion and analysis.
Companies API Endpoint Documentation Company data access pro
Accessing detailed company profiles.
Industries API Endpoint Documentation Company data
A list of industries available for company search.
Company Types API Endpoint Documentation Company data
A list of company types available for company search.
CSV and Parquet File Downloads Documentation Job data Company data access ultra
Weekly CSV and Parquet downloads for complete job data, company context, and analytical workflows.
Tags API Endpoint Documentation Job data
Role taxonomy tags (ROLE1/ROLE2/ROLE3) with recursive parent hierarchy.

Also check out our tutorials section for a collection of quick guides and example use cases.

API Integration

To use the JobData API securely and efficiently, keep your API or download keys private and share them only with trusted team members or contractors. Never expose keys in frontend code, URLs, or public repositories, as this can compromise security.

The API is strictly for backend use and should not be accessed directly from the frontend, such as in-browser JavaScript. Frontend requests will fail due to CORS errors, and exposing your API key in the browser creates security risks. Always use a secure backend server to call the API and relay the data to your frontend.

To ensure a better user experience and avoid unnecessary delays, cache API results in your backend. This reduces the number of requests to the API, improves performance, and ensures faster delivery of data to users. Use appropriate caching strategies based on the type of data, such as job listings or company details.

Rate limits

All API endpoints are publicly acessible, except for parameters and queries that require a certain subscription. Without a valid API key there is a maximum of ~10 requests per hour that can be made for testing purposes. This should be sufficient to get a sneak peek into how the API works and what the response structures look like.

Besides throttling for anonymous requests there are no special limitations for authorized calls to the API. The only restriction is that a client should not send more than 10 requests per second to any API endpoint and not more than 2 requests in parallel. It is strongly recommended that you gear your implementation towards a sequential request pattern and cache as much data locally or within your application as possible.

This is more of a technical measure to avoid peak loads and flooding the API with too many requests at once, especially as some queries can become quite complex and may take longer to process.

Timeouts and 500 errors

In some rare cases the /api/jobs/ endpoint can return a 500 Internal Server Error when a query is too expensive to complete. This usually means that the database query timed out or that the server took too long to build and render the complete JSON response. These errors are most often caused by the shape and size of the request, rather than by invalid credentials or missing data.

As a general rule, use a page_size somewhere between 100 and 2000. Very small and very large pages are edge cases: page_size=1 can be unexpectedly slow for some query shapes, while page_size=4000 can make the database query, object serialization and JSON response too large or slow. If a request returns a 500, try increasing page_size from 1 or reducing a large page size before changing other filters.

For broad or complex requests, progressively narrow the result set:

Split a large backfill into smaller date windows with published_since, published_until, min_age or max_age.
Use min_id and max_id ranges to divide large result sets into manageable batches.
Prefer specific country, region, state, city, company or other filters over one broad query, and avoid very deep page numbers when ID or date ranges can be used instead.
Keep multi-keyword filters such as title, location and company filters reasonably short. Each additional include or exclude term can add more conditions to the query. The same applies to full-text searches with multiple keywords/phrases.

Only request response fields that are needed. In particular, avoid enabling tags=true, salary_extras=true, embed_3sh=true, description_md=true, description_str=true or location_str=true unless they are required. Set description_off=true when the full description is not needed; this can substantially reduce response rendering time and size.

Configure your API client's connection timeout to at least 45 seconds. A shorter client-side timeout can close the connection prematurely while the API is still processing a valid result, especially for larger but otherwise successful responses.

If a request returns 500, do not repeatedly retry the same broad query in parallel. Retry sequentially with a short backoff after reducing the page size, search terms or result range. A successful narrower request confirms that the original query needs to be split. This is different from a 429 Too Many Requests response, which indicates throttling.