List Jobs
Fetch a list of jobs with filtering and search. Lists are paginated with opaque cursors: the response includes pagination.limit, pagination.next_page, and pagination.prev_page. There is no page query parameter.
How list pagination works
To fetch the next or previous window, send the same filters and
sort_by as before, and pass the token from the last response as cursor, or pass the same string using the next_page or prev_page query parameter.Freshness: published_after vs max_age
If you pass
published_after (ISO 8601), the API does not apply max_age for the same request. Use published_after for a strict calendar lower bound; use max_age for a rolling window (e.g. 7d).TypeScript
Full copy-paste types (including the FilterApplied union) live on the API types (TypeScript).
Allowed tokens for fields, exclude_fields, and extra_fields: id, title, location, locations, application_url, published, has_remote, is_active, expired_at, language, employment_type, salary_min, salary_max, salary_currency, salary_text, experience_level, experience_levels, company, description
GET
Default summary response (fastest)GET
Includes full job descriptionQuery Parameters
Search & Keywords
titlestringSearch by job title or keywords. Supports full-text search.
Example:
software engineersearchstringAlias of title (same behavior).
Example:
software engineersort_bystringSort order. Values: published (default), relevance (requires title).
Example:
relevanceGeographic Filtering
Pro Tip: Use the Geo Suggest API to find IDs for 100% accuracy.
city_idnumberFilter by specific city ID. Comma-separated.
Example:
5391959state_idnumberFilter by specific state ID. Comma-separated.
Example:
5332921country_idnumberFilter by specific country ID. Comma-separated.
Example:
233locationstringWhen no city_id, state_id, or country_id are provided: comma-separated ISO 3166-1 alpha-2 country codes (e.g. US,GB,DE). Invalid tokens are skipped.
Example:
US,CAremotebooleanSet to true for remote-only jobs.
Example:
trueField selection (list only)
Default list responses return a summary set of columns (no full description). Use the parameters below to trim or extend the payload. Unknown field names are ignored.
fieldsstringComma-separated allowlist: response includes only these columns (must be from the allowed set). Replaces the default summary projection.
Example:
id,title,company,publishedinclude_fieldsstringLegacy alias of fields — same behavior. Prefer fields for new integrations.
Example:
id,title,companyextra_fieldsstringComma-separated columns to add on top of the default summary (e.g. description).
Example:
descriptionexclude_fieldsstringComma-separated columns to remove from the resolved field set (applied after extra_fields).
Example:
description,companyCompensation & Seniority
salarystringFilter by salary range. Format: min,max. Omit max to get jobs with minimum salary only.
Example:
100000,150000 OR 100000(min)experience_levelstringValues: EN (Entry), MI (Mid), SE (Senior), EX (Executive). Comma-separated.
Example:
SE,EXFreshness & Pagination
published_afterstringISO 8601 timestamp: only jobs published at or after this instant. When set, max_age is not applied on the same request.
Example:
2024-05-01T00:00:00.000Zmax_agestringRolling window: positive integer with optional unit h (hours), d (days), w (weeks). A bare number is treated as days (e.g. 7 equals 7d). Omit if using published_after.
Example:
24h, 7d, 1w, or 7limitnumberResults per request. Max 100. Default 20.
Example:
50cursorstringOpaque token from the previous response’s pagination.next_page or pagination.prev_page.
Example:
(value from prior response)next_pagestringSame token as pagination.next_page, sent as a query parameter to load the next window.
Example:
(value from prior response)prev_pagestringSame token as pagination.prev_page, sent as a query parameter to load the previous window.
Example:
(value from prior response)Response Schema
The body includes data (jobs), pagination (see below), and meta.
Success Response Example
{
"data": [1 items],
"pagination": {3 keys},
"meta": {2 keys}
}
The Envelope
dataarrayAn array of Job objects matching your filters.
paginationobjectAlways has limit. next_page and prev_page are opaque cursor strings when more results exist in that direction; otherwise null or omitted. Pass those strings back as cursor, next_page, or prev_page on the following request.
metaobjectIncludes query_time_ms and filters_applied: an array describing which filters were honored, with one object per logical filter (geo IDs may produce one row per ID). Shapes vary by key — see the FilterApplied union on the API types page.
meta.filters_applied shapes
title,experience_level:key,value,display_label.salary:key,min,max,display_label.published_after,max_age:key,value,display_label(value is hours since cutoff for max_age).city_id/state_id/country_id:key,kind,name,display_label, plus the matching*_idfield.location(ISO2 codes from the location query param):key,value,display_label(code).- Remote-only filter (from
remote=true): rowkeyisremote_only;valueis alwaystrue.
The Company Object
NestedVerified metadata about the hiring organization, stored on the job object. Not every key is present for every listing—treat optional fields as nullable/missing.
company.namestringLegal name of the company.
company.logostring | nullNullableURL to the company's logo image.
company.website_urlstring | nullNullablePrimary website URL.
company.descriptionstring | nullNullableA brief overview of the company.
company.industrystring | nullNullableThe primary sector (e.g., 'Fintech', 'SaaS').
company.employee_countstring | nullNullableEstimated size range (e.g., '11-50', '5001-10000').
company.linkedin_urlstring | nullNullableDirect link to the company's LinkedIn profile.
company.twitter_urlstring | nullNullableDirect link to the company's Twitter/X profile.
company.github_urlstring | nullNullableDirect link to the company's GitHub organization.
company.facebook_urlstring | nullNullableDirect link to the company's Facebook page.
company.instagram_urlstring | nullNullableDirect link to the company's Instagram profile.
company.youtube_urlstring | nullNullableDirect link to the company's YouTube channel.
company.teamarrayAn array of key team members. Each object contains:
name: Full name of the team member.title: Job title or role (nullable).linkedin_url: Link to their professional profile (nullable).photo_url: URL to their profile photo (nullable).
The Location Object
Array ItemEach item in the locations[] array is a fully resolved geographic entity.
locations[].kindstring | nullNullableThe resolution granularity of this location.
city_state_country: Fully resolved.city_country: City and country resolved.city_state: City and state resolved.city,state, orcountry: Single level resolved.
locations[].display_labelstring | nullNullableFormatted name, e.g., 'San Francisco, CA, US'.
locations[].city_namestring | nullNullableThe name of the city.
locations[].city_idnumber | nullNullableThe unique ID for the city (if available).
locations[].state_namestring | nullNullableThe name of the state or province.
locations[].state_idnumber | nullNullableThe unique ID for the state (if available).
locations[].state_codestring | nullNullableShort code for the state (e.g., 'CA').
locations[].country_namestring | nullNullableThe name of the country.
locations[].country_idnumber | nullNullableThe unique ID for the country (if available).
locations[].country_codestring | nullNullableISO 3166-1 alpha-2 country code.
locations[].timezonestring | nullNullableThe IANA timezone ID (e.g., 'America/Los_Angeles').
locations[].is_remotebooleanIndicates if this specific location entry represents a remote setting.
locations[].is_primarybooleanTrue if this is the primary location for the job.
Interactive Testing
To see live data without writing code, use our Live API Playground or download one of our Starter Templates.