Skip to content

Search Jobs

Commands here use uv run kairos (a local checkout). In the Docker setup from Onboarding, run the same commands as docker compose exec backend kairos ....

Search lets you find jobs from multiple sources. Adzuna API is the primary source (free, structured JSON). LinkedIn and the Seek platform (JobsDB HK) scrapers are available as fallback.

Usage

# Default: Adzuna API, interactive country/city selection
uv run kairos jobs search "software engineer" -i

# Direct flags
uv run kairos jobs search "rust developer" --country AU --location Perth

# Multiple platforms
uv run kairos jobs search "backend" -c AU -l Sydney --platforms adzuna,linkedin

# Hong Kong (Seek runs as JobsDB there) and mainland China
uv run kairos jobs search "software engineer" -c HK --platforms seek,linkedin,tencent
uv run kairos jobs search "后端开发" -c CN -l Shenzhen --platforms tencent,bytedance,alibaba

# With filters
uv run kairos jobs search "python" -c US -l "San Francisco" \
  --salary-min 120000 \
  --job-type fulltime \
  --posted-within 7 \
  --max-results 30

Search Criteria

Field Flag Description Example
Keywords (positional) Role titles or skills "software engineer"
Country --country, -c Region code from the region registry AU, HK, CN
Location --location, -l City from predefined list Perth, Sydney, "New York City"
Interactive --interactive, -i Pick country & city from numbered list
Platforms --platforms, -p Comma-separated sources adzuna, seek, linkedin
Salary Min --salary-min Minimum salary 70000
Job Type --job-type, -t Employment type fulltime, parttime, contract
Posted Within --posted-within, -d Days since posted 7, 14, 30
Max Results --max-results, -n Maximum jobs to return 50

Available Cities

Each country has 15 predefined cities (14 cities + Remote):

AU US UK CA NZ
Sydney New York City London Toronto Auckland
Melbourne Los Angeles Manchester Vancouver Wellington
Brisbane Chicago Birmingham Montreal Christchurch
Perth San Francisco Leeds Calgary Hamilton
Adelaide Seattle Edinburgh Ottawa Tauranga
... ... ... ... ...

Use --interactive (-i) to see the full list.

How It Works

sequenceDiagram
    participant U as User
    participant CLI as CLI
    participant API as kairos-api
    participant AZ as Adzuna API
    participant SK as LinkedIn Scraper
    participant DB as PostgreSQL

    U->>CLI: kairos jobs search "developer"
    CLI->>API: POST /api/v1/jobs/search
    API->>AZ: GET api.adzuna.com/v1/api/jobs/au/search/1
    API->>SK: GET LinkedIn guest search
    AZ-->>API: JSON (structured)
    SK-->>API: HTML (parsed)
    API->>DB: UPSERT jobs (deduplicated, owner-scoped)
    API-->>CLI: Job list

Data Sources

Adzuna API (Primary)

  • Method: HTTP API calls to api.adzuna.com
  • Auth: Free API key from developer.adzuna.com
  • Data: Structured JSON — title, company, location, salary, description
  • Coverage: 19 countries (every Adzuna market: AU, US, UK, CA, NZ, AT, BE, BR, CH, DE, ES, FR, IN, IT, MX, NL, PL, SG, ZA)
  • Limits: ~250 requests/day (free tier)
  • Reliability: High — official API, no scraping

Seek platform — JobsDB HK (Fallback Scraper)

  • One adapter for every Seek-platform site; the host comes from platform/seek/sites.toml, which bundles JobsDB HK only
  • Seek AU and NZ are not bundled: Cloudflare's bot challenge answers every scripted request. Australia is covered by Adzuna and LinkedIn; add a Seek site under [platforms.seek.sites.<CODE>] in config.toml if you want to try one
  • JobsDB salaries are monthly and are stored annualised
  • Rate limit: 2-5 second delay between requests
  • ~22 results per page
  • No login required

Seek AU — from Seek's recommendation emails

  • Seek emails you about a dozen recommended jobs a day; with [jobs] seek_mail = true each harvest reads them through Kioku ([tracking], which needs KAIROS_KIOKU_ACCESS_CLIENT_ID and _SECRET) and saves their jobs as platform seek_mail (decision 0011)
  • Each job brings its title, company, location, any salary and the email's highlight bullets; the link keeps only the job id, never the email's personal token
  • No adapter can open or check Seek pages, so these jobs are archived seek_mail_expiry_days (30) after they first appeared, unless you applied. For one worth pursuing, open it in a browser and add the full ad with kairos jobs add <url> --description-file ad.txt

LinkedIn (Fallback Scraper)

  • Public job listings via guest API (no login required)
  • Rate limit: 2-6 second delay between requests
  • 25 results per page

JobTech (Platsbanken, Sweden)

  • Arbetsförmedlingen's official open JobSearch API: every Platsbanken ad, no key, no login
  • City (municipality), remote and posted-within filters run on the server
  • Search hits carry the whole ad, so no detail page is read

The Hub (Nordic startups)

  • Startup jobs in Denmark, Sweden, Norway and Finland from thehub.io, no key, no login
  • Reads the site's own undocumented JSON API, so it is opt-in and can break when the site changes
  • Country, keywords and job type filter on the server; city and remote filter in Kairos
  • No date filter: every search returns whatever is open, newest not first
  • Each new posting costs one detail request for its description

Company career sites (Tencent, ByteDance, Alibaba)

  • Each company's own public JSON API, no login; mainland China (Tencent also Hong Kong)
  • Postings are mostly in Chinese, so Chinese keywords ("后端开发") match far more
  • The APIs only filter by keyword; region, city and age are filtered client-side

~~Indeed~~ (Not read)

  • Indeed's official MCP serves Claude connectors only, so the harvest cannot use it; in a Claude chat with the Indeed connector, search there and add the jobs you want with kairos jobs add
  • Scraping Indeed means getting past Cloudflare's protection, which Kairos does not do

Deduplication

Jobs are deduplicated by (owner_id, platform, platform_job_id) using PostgreSQL UPSERT. Re-running a search updates the same user's existing jobs rather than creating duplicates; two users can independently track the same listing without colliding.

One role posted on two boards is also kept once. Each saved job carries a role_key (company without legal-form suffixes, title without bracketed or dash-separated qualifiers, any script; see kairos.core.role_key). A posting from a new board whose role_key and region match a saved, still-open job from another board is not saved; the existing row stands for it. An archived twin does not count, so a role closed on one board and open on another is saved again. Within one board, its own ids decide.

Automatic harvest

While the API runs it can search the boards on a timer and save what they find, so the job list fills itself. It is off until harvest_hours is above 0; turning it on is the opt-in to read each board in harvest_platforms on that timer.

[jobs]
harvest_hours = 12                         # 0 = off
harvest_keywords = ["software engineer"]   # [] = [profile] target_roles
harvest_regions = ["HK", "CN"]             # [] = regions in [profile] preferred_cities
harvest_platforms = []                     # [] = every board that serves the region
harvest_board_cities = { tencent = { CN = ["Shenzhen"] } }  # extra cities on one board

harvest_board_cities adds cities searched on one board only, on top of the preferred ones; above, Tencent's Shenzhen roles are harvested while the other mainland boards keep to the preferred cities. It has no effect in a region with no preferred city, where the whole region is already searched.

Each run searches every keyword × region × preferred city (the whole region when it has none) × board, posted within [search] posted_within_days. A board that fails or has no credentials (Adzuna without ADZUNA_APP_ID/ADZUNA_APP_KEY) is logged and skipped; the rest still run. Found postings are stamped as checked, and the availability check archives them once their site reports them closed. POST /api/v1/jobs/harvest runs the same searches on request.

Web frontend

The same search is available from the web app: every CLI flag (--country, --location, --platforms, --salary-min, --job-type, --posted-within, --max-results) has a UI control. Press Enter to submit; per-platform errors render inline so a scraper failure doesn't hide successful Adzuna results.

Work Rights

Jobs carry three work rights fields (populated during JD analysis):

Field Meaning
PR Required Employer requires permanent residency
Citizenship Required Employer requires citizenship
Visa Sponsorship Employer is willing to sponsor a visa

These fields are nullable — many JDs don't state requirements explicitly.

Fit scores

Saved postings can carry a 0-100 fit score and a one-line reason. The scorer judges each posting against your base resume (kairos resume import cv.md), plus ~/.config/kairos/watch-profile.md when that file holds anything the resume leaves out. [profile.fit] sets how much each factor counts. Settings → Fit scoring in the web app edits the same values:

[profile.fit]
skills = "high"                      # how strictly a stack or seniority gap counts
industries = ["automotive (dealer systems, OEMs, suppliers)", "ERP (SAP, Oracle, in-house)"]
industry = "high"                    # a role in one of `industries`
career_value = "medium"              # big names whose experience compounds
admired_employers = []               # e.g. ["Atlassian", "Canva"]; [] = general reputation
work_life_balance = "high"           # long-hours cultures count against a role
foreign_companies = "medium"         # multinational over local employers
foreign_companies_in = ["CN", "HK"]  # where that applies; [] = every region
needs_sponsorship_in = ["AU"]        # roles there that will not sponsor are capped at 40
sponsorship_offered_points = 20      # ...and ones that say they sponsor gain this many
listed_sponsor_points = 10           # ...and silent ones from a listed sponsor gain this many
notes = ""

Nothing about places, industries or employers is built into the scorer's brief. It names only what this table holds, so the same build serves a nurse in Toronto or an engineer in Shanghai. The example above is one user's choice.

Each level caps how far that factor can move a score: off 0, low 5, medium 10, high 20 points. skills works differently. At high, a real gap puts the score below 50; at low, adjacent skills are enough. Older configs that used true/false still load: true becomes medium and false becomes off.

When two of these pull apart, say a big name with long hours, the reason names the trade-off. The scorer is also told the places you are open to (each harvested region's preferred and board cities), which override any location wish in the profile text. A posting saved without a description (LinkedIn and JobsDB search pages carry none) has its detail page read before it is scored.

POST /api/v1/jobs/score-fit scores unscored postings, newest first. With rescore_before it also redoes older scores (kairos jobs score --rescore --all). With [jobs] fit_scoring_batch above 0, the API also scores that many after each harvest. Three failures in a row, or a missing key, stop the run without touching any score.

[jobs]
fit_scoring_batch = 100
fit_model = ""              # "" = haiku on claude-cli, the [llm] model on litellm
fit_effort = ""             # claude-cli: low, medium, high, xhigh, max; "" = low
fit_concurrency = 4         # postings scored at once (1-16)

[llm]
backend = "claude-cli"      # Claude Code headless on your subscription; or "litellm"

Postings are scored fit_concurrency at a time. Detail pages are still read through one adapter per board, so each board's rate limiter paces them. Each claude -p call is its own process, so on a small machine keep the concurrency low.

[llm] backend is shared by every LLM call, so resume tailoring runs on the same subscription or key (see LLM integration). claude-cli needs a signed-in claude on the API's PATH ([llm] claude_bin names another path); a container reads CLAUDE_CODE_OAUTH_TOKEN from its environment. litellm uses the [llm] model and its API key instead. On a sample of nine postings, haiku/low ranked them like sonnet/medium and caught the same dealbreakers (clearance, citizenship, seniority).