API reference · Jobs

Search open jobs

POSThttps://trawle.com/v1/jobs/search

Open jobs matching a JobQuery, newest first (or by pay). Paginate with cursor. For a daily "what's new" run, store nextSince and pass it back as postedSince next time. Data refreshes once a day.

Request body

application/json · SearchJobsRequest

queryobject · JobQueryrequired
A job search. Values inside one filter are OR, filters are AND. The same object is used by the website's links and saved views.
14 properties
- qstringoptional
  Free text. Every word must start a word of the job title or department (any order, react matches "React/TypeScript"), or every word must start a word of the company name.
  Limits
  2 to 100 characters
  Example
  react
- rolesarray<string>optional
  Role slugs, any of them. Look slugs up with GET /v1/roles?q= (MCP find_occupation).
  Limits
  1 to 20 items, items: pattern ^[a-z0-9][a-z0-9-]{0,79}$
  Example
  ["frontend-engineer"]
- familiesarray<string>optional
  Job family slugs (any role in the field). List them with GET /v1/families.
  Limits
  1 to 10 items, items: pattern ^[a-z0-9][a-z0-9-]{0,79}$
  Example
  ["software-engineering"]
- placesarray<integer>optional
  Where the person wants to work from, as GeoNames ids (multi-country regions are negative, -1 is worldwide). Matches onsite/hybrid jobs located in the place plus remote jobs open to people living there. Look ids up with GET /v1/places?q= (MCP resolve_location).
  Limits
  1 to 20 items
  Example
  [2618425]
- companiesarray<string>optional
  Company slugs. Look them up with GET /v1/companies?q=.
  Limits
  1 to 50 items, items: pattern ^[a-z0-9][a-z0-9-]{0,79}$
  Example
  ["stripe"]
- workplacearray<string>optional
  One of
  remotehybridonsite
  Limits
  at least 1 item
- seniorityarray<string>optional
  One of
  internentrymidseniorleadprincipaldirectorvpexecutive
  Limits
  at least 1 item
- employmentarray<string>optional
  One of
  full_timepart_timecontracttemporaryinternshipapprenticeshipseasonalvolunteer
  Limits
  at least 1 item
- postingLanguagesarray<string>optional
  Languages the posting is written in, ISO 639-1, any of them. Detected from the description; jobs without one never match. Not the languages a job requires (JobDetail.languages).
  Limits
  1 to 10 items, items: pattern ^[a-z]{2}$
  Example
  ["en"]
- salaryobject · SalaryRangeoptional
  Annual pay range, both ends inclusive, either end open (null). Jobs match when their own range overlaps it after converting currencies; jobs without pay never match.
  3 properties
  mininteger | nullrequired
  Limits
  at least 0
  Example
  60000
  maxinteger | nullrequired
  Limits
  at least 0
  currencystringrequired
  One of
  USDEURGBPDKKSEKNOKCHFCADAUD
- paystringoptional
  listed: only jobs that show pay.
  One of
  listed
- postedstringoptional
  First seen by Trawle within this window. For scheduled agents, prefer postedSince with the nextSince of the previous run.
  One of
  1d3d7d30d
- repostsstringoptional
  Reposts are jobs seen before under another id, or closed and reopened. hide keeps only originals.
  One of
  hideonly
- sortstringoptional
  newest (default) or pay (highest annual pay first; only jobs that show pay).
  One of
  newestpay
cursorstring | nulloptional
nextCursor from the previous page.
limitintegeroptional
Default 25.
Limits
1 to 100
postedSincestring<date-time>optional
Only jobs first seen at or after this instant. Scheduled agents pass the nextSince of their previous run to get only new jobs.
Example
2026-10-31T06:12:00.000Z

Responses

200A page of jobs.SearchJobsResult

jobsarray<object> · JobSummaryrequired
19 propertiesper item
- idstringrequired
  Stable public id; never changes across scans.
  Example
  1234567
- titlestringrequired
- companyobject · CompanyRefrequired
  3 properties
  slugstringrequired
  Example
  stripe
  namestringrequired
  Example
  Stripe
  domainstring | nullrequired
  Example
  stripe.com
- roleobject | null · Refrequired
  2 properties
  slugstringrequired
  namestringrequired
- familyobject | null · Refrequired
  2 properties
  slugstringrequired
  namestringrequired
- locationsarray<object> · PlaceRefrequired
  Where the job is located (or, for remote jobs, who may apply), most specific first.
  3 propertiesper item
  idintegerrequired
  GeoNames id (regions are negative).
  namestringrequired
  Example
  Copenhagen
  countrystring | nullrequired
  ISO 3166-1 alpha-2 country code; null for multi-country regions.
  Example
  DK
- workplacestring | nullrequired
  One of
  remotehybridonsite
- remoteScopestring | nullrequired
  For remote jobs: who may apply, in words ("Anywhere", "United States only").
- senioritystring | nullrequired
  One of
  internentrymidseniorleadprincipaldirectorvpexecutive
- employmentTypestring | nullrequired
  One of
  full_timepart_timecontracttemporaryinternshipapprenticeshipseasonalvolunteer
- salaryobject | null · Salaryrequired
  Pay as the employer listed it (not converted).
  4 properties
  mininteger | nullrequired
  maxinteger | nullrequired
  currencystring | nullrequired
  ISO 4217 code.
  Example
  EUR
  periodstringrequired
  One of
  yearmonthweekdayhour
- firstSeenAtstring<date-time>required
  First seen by Trawle under this id.
  Example
  2026-10-31T06:12:00.000Z
- lastSeenAtstring<date-time>required
  Last time a daily scan saw it open on the employer's site.
  Example
  2026-10-31T06:12:00.000Z
- postedAtstring<date-time> | nullrequired
  "Date posted" from the employer's ATS, when it has one. Often unreliable.
  Example
  2026-10-31T06:12:00.000Z
- openSincestring<date-time>required
  First time any posting of this job (reposts included) was seen; days open count from here.
  Example
  2026-10-31T06:12:00.000Z
- repostCountintegerrequired
  Earlier postings of this job under other ids, plus reopenings. 0 = original.
- closedAtstring<date-time> | nullrequired
  When it disappeared; null while open.
  Example
  2026-10-31T06:12:00.000Z
- applyUrlstringrequired
  The employer's own posting (their ATS).
- urlstringrequired
  This job on Trawle.
totalintegerrequired
Matches, capped at 10,000 (totalCapped).
totalCappedbooleanrequired
nextCursorstring | nullrequired
Next page; null on the last.
labelsobjectrequired
Names for the ids and slugs in the query, keyed filter:value (places:2618425 → Copenhagen). Unknown values are absent and matched nothing.
dataDatestring<date-time>required
When the data was last refreshed (daily).
Example
2026-10-31T06:12:00.000Z
nextSincestring<date-time>required
Pass as postedSince on the next scheduled run to get only jobs that are new since this one.
Example
2026-10-31T06:12:00.000Z

400Invalid request: see error.issues and error.hint.Error

errorobjectrequired
4 properties
- codestringrequired
  Machine-readable: invalid_request, not_found, forbidden, rate_limited, internal.
  Example
  invalid_request
- messagestringrequired
  Example
  places: expected an array of GeoNames ids
- hintstringoptional
  What to do next, e.g. which lookup to call first.
  Example
  Resolve place names to ids with GET /v1/places?q=
- issuesarray<object>optional
  Validation problems, one per invalid field.
  2 propertiesper item
  pathstringrequired
  messagestringrequired

PreviousOverview NextCheck whether jobs are still open

POST /v1/jobs/search

curl -X POST "https://trawle.com/v1/jobs/search" \
  -H "Content-Type: application/json" \
  -d '{
  "query": {
    "roles": ["frontend-engineer"],
    "places": [2618425],
    "workplace": ["hybrid", "remote"]
  },
  "limit": 25
}'

Response

{
  "jobs": [
    {
      "id": "4419023",
      "title": "Senior Frontend Engineer",
      "company": {
        "slug": "lumen-labs",
        "name": "Lumen Labs",
        "domain": "lumenlabs.example"
      },
      "role": {
        "slug": "frontend-engineer",
        "name": "Frontend Engineer"
      },
      "family": {
        "slug": "software-engineering",
        "name": "Software Engineering"
      },
      "locations": [
        {
          "id": 2618425,
          "name": "Copenhagen",
          "country": "DK"
        }
      ],
      "workplace": "hybrid",
      "remoteScope": null,
      "seniority": "senior",
      "employmentType": "full_time",
      "salary": {
        "min": 720000,
        "max": 900000,
        "currency": "DKK",
        "period": "year"
      },
      "firstSeenAt": "2026-10-30T06:12:00.000Z",
      "lastSeenAt": "2026-10-31T06:12:00.000Z",
      "postedAt": "2026-10-29T00:00:00.000Z",
      "openSince": "2026-09-14T06:10:00.000Z",
      "repostCount": 1,
      "closedAt": null,
      "applyUrl": "https://job-boards.greenhouse.io/lumenlabs/jobs/7712001",
      "url": "https://trawle.com/jobs/4419023"
    }
  ],
  "total": 38,
  "totalCapped": false,
  "nextCursor": "MjAyNi0xMC0zMFQwNjoxMjowMC4wMDBafDQ0MTkwMjM",
  "labels": {
    "roles:frontend-engineer": "Frontend Engineer",
    "places:2618425": "Copenhagen"
  },
  "dataDate": "2026-10-31T06:12:00.000Z",
  "nextSince": "2026-10-31T09:30:00.000Z"
}