API reference · Jobs

Search open jobs (cacheable)

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

The same results and cursors as POST /v1/jobs/search. Pass query as a JSON-encoded JobQuery. Results never depend on cookies or viewer location. Use POST for queries too large for a URL.

Authentication

Header x-api-key: Read-only API key from https://trawle.com/account#api-keys. 1,000 requests per daily window. Anonymous requests are also supported with a per-IP limit.

Parameters

Query

querystringoptional
JSON-encoded JobQuery; default {}.
Limits
at most 6000 characters
cursorstringoptional
Limits
1 to 2000 characters
limitintegeroptional
Limits
1 to 100
postedSincestring<date-time>optional

Responses

200A page of jobs.SearchJobsResult

jobsarray<object> · JobSummaryrequired
31 propertiesper item
- idstringrequired
  Stable public id; never changes across scans.
  Example
  019a3b6e-8f2c-7d41-9b0e-5c3f7a2d4e81
- titlestringrequired
- postingIdstringoptional
  The concrete source posting whose facts and application link are shown.
- postingCountintegeroptional
  Currently publishable source postings grouped into this job; not a headcount estimate.
  Limits
  at least 0
- departmentstring | nulloptional
  Department or team as supplied by the employer; null when not stated.
  Default
  null
- requirementsarray<string>optional
  Up to three key must-have qualifications extracted from the posting. Preferred qualifications are excluded. Empty when not yet extracted or none are explicitly stated; not an exhaustive list.
  Default
  []
  Limits
  at most 3 items, items: 1 to 160 characters
- summarystring | nulloptional
  One-paragraph summary (generated).
  Default
  null
- experienceYearsobject | nulloptional
  Default
  null
  2 properties
  mininteger | nullrequired
  maxinteger | nullrequired
- companyobject · CompanyRefrequired
  4 properties
  slugstringrequired
  Example
  stripe
  namestringrequired
  Example
  Stripe
  domainstring | nullrequired
  Example
  stripe.com
  isAgencybooleanrequired
  A recruitment or staffing agency posting jobs for its clients, not its own. Job search leaves these out unless agencies is set.
- 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
  Legacy earliest observation of a similar posting. Not continuous time open or proof of the same requisition.
  Example
  2026-10-31T06:12:00.000Z
- repostCountintegerrequired
  Legacy total of possible earlier postings plus reopenings. Use possibleRepostCount and reopenCount separately.
- possibleRepostCountintegeroptional
- reopenCountintegeroptional
- historyStartedAtstring<date-time> | nulloptional
  Detailed scan change capture began here. Earlier changes may be missing; null means capture has not started.
  Example
  2026-10-31T06:12:00.000Z
- lastListingChangeAtstring<date-time> | nulloptional
  Example
  2026-10-31T06:12:00.000Z
- relatedPostingsarray<object>optional
  Up to eight earlier matching postings, strongest evidence first. source_identity requires matching URL, ATS and requisition id on a confirmed board move. A similar title/location is only possible; never automatically merge decisions for it.
  Limits
  at most 8 items
  4 propertiesper item
  idstringrequired
  titlestringrequired
  firstSeenAtstring<date-time>required
  Example
  2026-10-31T06:12:00.000Z
  confidencestringrequired
  One of
  source_identitypossible
- 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.
- matchReasonsarray<object>optional
  Query-specific evidence returned by search, not a candidate fit score. Classification is not proof of an employer requirement. Absent outside search.
  3 propertiesper item
  labelstringrequired
  evidencestringrequired
  explanationstringrequired
totalintegerrequired
Matches, capped at 10,000 (totalCapped).
totalCappedbooleanrequired
nextCursorstring | nullrequired
Next page; null on the last.
selectedPlacesarray<object> · PlaceRefoptional
Resolved query.places, independent of matching jobs. Includes country codes for location-aware currency defaults; unknown ids are omitted and multi-country regions have a null country.
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
labelsobjectrequired
Names for the ids and slugs in the query, keyed filter:value (places:2618425 → Copenhagen). Excluded companies use companies:slug too. Unknown inclusions match nothing; unknown exclusions remove nothing. Unknown labels are absent.
dataDatestring<date-time>required
When the data was last refreshed (daily).
Example
2026-10-31T06:12:00.000Z
nextSincestring<date-time>required
Safe discovery boundary, not response time. Stable across cached pages and pagination. Save only after finishing all pages; pass unchanged as postedSince next run and deduplicate by job id because boundaries overlap. May remain unchanged while scans are incomplete; Unix epoch before a safe scan exists.
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

401Invalid, expired or revoked API key.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

429Rate limit reached. Respect Retry-After and cache results.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 NextSearch open jobs

GET /v1/jobs/search

curl "https://trawle.com/v1/jobs/search" \
  -H "x-api-key: $TRAWLE_API_KEY"

Response

{
  "jobs": [
    {
      "id": "019a3b6e-8f2c-7d41-9b0e-5c3f7a2d4e81",
      "title": "string",
      "postingId": "string",
      "postingCount": 0,
      "department": null,
      "requirements": [],
      "summary": null,
      "experienceYears": null,
      "company": {
        "slug": "stripe",
        "name": "Stripe",
        "domain": "stripe.com",
        "isAgency": true
      },
      "role": {
        "slug": "string",
        "name": "string"
      },
      "family": {
        "slug": "string",
        "name": "string"
      },
      "locations": [
        {
          "id": 0,
          "name": "Copenhagen",
          "country": "DK"
        }
      ],
      "workplace": "remote",
      "remoteScope": "string",
      "seniority": "intern",
      "employmentType": "full_time",
      "salary": {
        "min": 0,
        "max": 0,
        "currency": "EUR",
        "period": "year"
      },
      "firstSeenAt": "2026-10-31T06:12:00.000Z",
      "lastSeenAt": "2026-10-31T06:12:00.000Z",
      "postedAt": "2026-10-31T06:12:00.000Z",
      "openSince": "2026-10-31T06:12:00.000Z",
      "repostCount": 0,
      "possibleRepostCount": 0,
      "reopenCount": 0,
      "historyStartedAt": "2026-10-31T06:12:00.000Z",
      "lastListingChangeAt": "2026-10-31T06:12:00.000Z",
      "relatedPostings": [
        {
          "id": "string",
          "title": "string",
          "firstSeenAt": "2026-10-31T06:12:00.000Z",
          "confidence": "source_identity"
        }
      ],
      "closedAt": "2026-10-31T06:12:00.000Z",
      "applyUrl": "string",
      "url": "string",
      "matchReasons": [
        {
          "label": "string",
          "evidence": "string",
          "explanation": "string"
        }
      ]
    }
  ],
  "total": 0,
  "totalCapped": true,
  "nextCursor": "string",
  "selectedPlaces": [
    {
      "id": 0,
      "name": "Copenhagen",
      "country": "DK"
    }
  ],
  "labels": {
    "key": "string"
  },
  "dataDate": "2026-10-31T06:12:00.000Z",
  "nextSince": "2026-10-31T06:12:00.000Z"
}