Search recipes

There are two search endpoints over the same index:

GET /api/jobs — query-string filters, comma-separated multi-values. Best for URL-shareable queries and lightweight integrations.
POST /api/jobs/search — typed JSON body with include/exclude and range filters. Best for filter UIs and anything programmatic.

Both are page-based and relevance-ranked. To export the whole corpus, use the feed instead — it is cheaper per job and immune to records shifting between pages.

Filter values are matched literally. An unrecognised value is not an error — it returns 200 with total: 0. Send the canonical keys from Enums, not the display values that come back on a job.

Parameter equivalence

Concept	`GET` query param	`POST` body field
Text query	`q` (single string)	`queries` (string array, OR’d)
Location	`location` (single string)	`locations` (string array)
Sources	`sources` (comma-separated)	`sources` (string array)
Work model	`work_model` (comma-separated)	`work_models` (string array)
Employment type	`employment_type` (comma-separated)	`employment_types` (string array)
Experience level	`experience_level` (comma-separated)	`experience_levels` (string array)
Skills	`skills` (comma-separated)	`skills` (include/exclude object)
Industries	`industries` (comma-separated)	`industries` (include/exclude object)
Companies	— (not available on GET)	`companies` (include/exclude object)
Salary	`min_salary_usd`, `max_salary_usd`	`salary_usd` (`{min, max}` object)
Posted window	`posted_after`, `posted_before`	`posted_after`, `posted_before`
Indexed window	`discovered_after`, `discovered_before`	`discovered_after`, `discovered_before`
Search body text	`search_description` (default `true`)	`search_description`
Facet selection	`include_facets` (comma-separated)	`include_facets` (string array)
Field selection	`include_fields` (comma-separated)	`include_fields` (string array)
Pagination	`page` (1), `page_size` (25, max 100)	`page`, `page_size`

POST array fields are not comma-split. "employment_types": ["full-time,contract"] is one literal value and matches nothing — write ["full-time", "contract"].

How text queries match

By default a query is a broad relevance search: each term is matched against the job title, company name, popular skills, and summary, with typo tolerance. That maximises recall, so data engineer can also surface roles whose title is not “data engineer” because the words appear elsewhere. Set search_description=false to keep the query out of the description body — noticeably faster and much more precise.

Quoted phrases match titles only

Wrap a query in double quotes to switch that entry to a strict match: the exact phrase must appear contiguously in the job title. Typo tolerance and partial-word matching are off.

{ "queries": ["\"Quantitative Developer\"", "\"Quant Developer\""] }

Only jobs whose title contains either phrase are returned. You can mix quoted and unquoted entries — each is evaluated independently and the results combined:

{ "queries": ["\"Quant Developer\"", "machine learning engineer"] }

On GET /api/jobs pass the quotes inside the value: ?q="Quantitative Developer".

A request may carry at most 10 positive terms in queries. Exceeding that returns a real 400 rather than silently dropping the extras, so you always know exactly what was searched. Negative - exclusions do not count toward the limit.

Recipes

Keyword plus location

curl "https://connect.jobo.world/api/jobs?q=data+engineer&location=Seattle&page_size=10" \
  -H "X-Api-Key: $JOBO_API_KEY"

from jobo_enterprise import JoboClient

with JoboClient(api_key="YOUR_API_KEY") as client:
    results = client.search.search(q="data engineer", location="Seattle", page_size=10)
    print(f"{results.total} matches across {results.total_pages} pages")
    for job in results.jobs:
        print(f"  {job.title} — {job.company.name} ({job.workplace_type})")

Remote senior roles in a salary band

Remember: senior, not senior level.

curl -G "https://connect.jobo.world/api/jobs" \
  -H "X-Api-Key: $JOBO_API_KEY" \
  --data-urlencode "q=backend engineer" \
  --data-urlencode "work_model=remote" \
  --data-urlencode "experience_level=senior" \
  --data-urlencode "employment_type=full-time" \
  --data-urlencode "min_salary_usd=150000" \
  --data-urlencode "max_salary_usd=250000"

results = client.search.search(
    q="backend engineer",
    work_model="remote",
    experience_level="senior",
    employment_type="full-time",
    min_salary_usd=150_000,
    max_salary_usd=250_000,
)

Do not use the SDK’s EmploymentType enum — its members serialize as full_time/part_time with underscores, which the API does not accept and which silently returns zero results. Pass the hyphenated string literals "full-time" / "part-time" instead. WorkModel and ExperienceLevel are safe, except that ExperienceLevel is missing intern.

Include and exclude skills

skills, companies, and industries accept an include/exclude object on the typed endpoint. Entries within include are OR’d; anything in exclude is removed.

{
  "queries": ["backend developer"],
  "skills": { "include": ["python", "go"], "exclude": ["php"] }
}

from jobo_enterprise import InclusionExclusionFilter

results = client.search.search_advanced(
    queries=["backend developer"],
    skills=InclusionExclusionFilter(include=["python", "go"], exclude=["php"]),
)

Target or exclude specific employers

Only available on the typed endpoint. Excluding staffing agencies is the most common use.

{
  "queries": ["software engineer"],
  "companies": { "exclude": ["Acme Staffing", "Generic Recruiting Co"] }
}

Open-ended salary range

Omit either bound.

{ "salary_usd": { "min": 200000 } }

from jobo_enterprise import RangeFilter

results = client.search.search_advanced(salary_usd=RangeFilter(min=200_000))

Posted window vs discovered window

posted_after / posted_before filter on the employer’s posting date, which some platforms do not expose. discovered_after / discovered_before filter on when Jobo indexed the job — use these when you need a guarantee that nothing is missed.

{
  "queries": ["backend engineer"],
  "posted_after": "2026-06-01T00:00:00Z",
  "posted_before": "2026-07-01T00:00:00Z"
}

Everything at once

{
  "queries": ["backend engineer", "platform engineer"],
  "locations": ["San Francisco", "New York", "Seattle"],
  "sources": ["greenhouse", "lever", "ashby"],
  "skills": { "include": ["go", "rust", "kubernetes"], "exclude": ["php"] },
  "companies": { "exclude": ["Acme Staffing"] },
  "work_models": ["remote", "hybrid"],
  "employment_types": ["full-time"],
  "experience_levels": ["senior", "lead"],
  "salary_usd": { "min": 150000, "max": 300000 },
  "posted_after": "2026-01-15T00:00:00Z",
  "page": 1,
  "page_size": 50
}

Iterate every match

iter_jobs pages for you.

for job in client.search.iter_jobs(
    queries=["backend engineer"],
    locations=["London"],
    page_size=100,
):
    print(job.title, job.company.name)

Shrinking the response

Every job carries all its fields by default, and description dominates payload size. include_fields keeps only the non-core fields you ask for — core fields (id, title, company, locations, compensation, dates, source, flags) are always returned.

`include_fields`	Result
omitted	Full job, every field. The default.
`["description","benefits"]`	Core plus `description` and `benefits`.
`[]` (or empty on GET)	Core fields only.

The five omittable fields are description, summary, qualifications, responsibilities, and benefits. On GET pass a comma-separated string (?include_fields=description,benefits); send ?include_fields= for core only. Unknown names are dropped, and any non-core field you did not request comes back empty ("" / []) rather than absent. Dropping description is the single biggest win for high-volume search.

Responses include a facets object of server-computed counts, keyed by canonical value.

Facet key	Faceted on	Default?
`work_model`	work model	✅
`experience_level`	experience level	✅
`employment_type`	employment type	✅
`sources`	`provider_id`	✅
`industries`	company industries	Opt-in
`skills`	skill names	Opt-in — high cardinality, adds latency

`include_facets`	Result
omitted	The four defaults.
`["skills"]`	Only `skills`.
`[]` (or empty on GET)	No facets — `"facets": {}`.

{
  "facets": {
    "work_model": [
      { "key": "remote", "count": 5230 },
      { "key": "hybrid", "count": 2847 },
      { "key": "onsite", "count": 1540 }
    ],
    "experience_level": [
      { "key": "senior", "count": 4521 },
      { "key": "mid", "count": 3892 }
    ]
  }
}

Facet keys are the canonical values, so you can feed a key straight back in as a filter value. This is not true of the display values on a job — see Enums.

Three facet behaviours surprise people:

Unknown facet names are silently dropped, so a request whose include_facets contains only unknown names (e.g. the plural typo work_models) returns no facets rather than the defaults.
At most 8 buckets are returned per facet, and counts are approximate. Take exact totals from total, never from summing facet counts.
A facet with no buckets is omitted from the facets object entirely rather than appearing as an empty array.

Get started

How-to guides

Changelog

Parameter equivalence

How text queries match

Quoted phrases match titles only

Recipes

Keyword plus location

Remote senior roles in a salary band

Include and exclude skills

Target or exclude specific employers

Open-ended salary range

Posted window vs discovered window

Everything at once

Iterate every match

Shrinking the response

Facets

​Parameter equivalence

​How text queries match

​Quoted phrases match titles only

​Recipes

​Keyword plus location

​Remote senior roles in a salary band

​Include and exclude skills

​Target or exclude specific employers

​Open-ended salary range

​Posted window vs discovered window

​Everything at once

​Iterate every match

​Shrinking the response

​Facets

Parameter equivalence

How text queries match

Quoted phrases match titles only

Recipes

Keyword plus location

Remote senior roles in a salary band

Include and exclude skills

Target or exclude specific employers

Open-ended salary range

Posted window vs discovered window

Everything at once

Iterate every match

Shrinking the response

Facets