Query language

Three ways to search text

Pick the simplest one that does the job.

Boolean search with title_advanced and description_advanced

Send an expression in title_advanced to search titles, or in description_advanced to search descriptions. Each parameter takes one expression of up to 200 characters.

GET /v1/jobs/count?title_advanced=nurse%20AND%20NOT%20manager
GET /v1/jobs/count?title_advanced=engineer:*%20AND%20(senior%20%7C%20staff)

Operators are not case sensitive. NOT binds tighter than AND, and AND binds tighter than OR, so use parentheses when you mix them. An expression can have up to 64 tokens.

Two rules cause most 400 errors. First, put an operator between words: senior engineer is rejected, and senior AND engineer works. Second, every expression needs at least one positive word: NOT manager alone is rejected, and so is a OR NOT b. A bad expression returns 400 invalid_request with the message "must be a valid Boolean search expression".

Examples with real counts

Counts are current jobs on October 14, 2026, from GET /v1/jobs/count.

Elasticsearch-style queries

POST /v1/jobs/search/es_dsl accepts a JSON body with a query and the usual paging and shaping options. Use it when you already have Elasticsearch queries or want a nested yes/no structure.

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"country": "US"}},
        {"term": {"work_arrangement": "remote"}},
        {"range": {"pay_min": {"gte": 150000}}},
        {"exists": {"field": "application_url"}}
      ],
      "must": [{"match": {"title_advanced": "data AND (engineer OR scientist)"}}]
    }
  },
  "fields": ["job_id", "title", "employer_name"],
  "limit": 25
}

The body may contain these top-level keys: query (required), limit, cursor, sort, fields, include and description_format. The body can be up to 16,384 bytes and must be sent as application/json. Responses look like GET /v1/jobs responses.

Supported clauses

Fields and aliases

Any filter name works as a field in term, terms, match and match_phrase: for example country, state, city, work_arrangement, employment_type, source, company_id, pay_currency, title_advanced and description_advanced. The list of filters is on the job filters page. These aliases are also accepted:

Rules and limits

• Clauses nest up to 32 levels deep.
• should accepts only term or match clauses on one field, country or employment_type, with up to 10 values. It means "any of these".
• must_not accepts source (which becomes exclude_source) and exists clauses only.
• Clauses are combined with AND. Two clauses that set the same single-value filter to different values are rejected, and so is an AND of different country, employment_type, currentness or include lists, because that would change which jobs match.
• Anything else (aggregations, scripts, fuzzy or wildcard clauses, unknown fields) returns 400 invalid_request and the message names the clause or field it rejected.
• A query that runs longer than 10 seconds returns 504 query_timeout and uses no records. Add a country, state, source or date range and try again.