Short definitions, A to Z. Each links to the page that explains it in full. Names in code are exact API field or value names.
Already paid
Section titled “Already paid”A job you were charged for before. Returning it again, from any endpoint, costs 0 credits. Counted in metadata.jobs_already_paid and shown in the ledger with reason: already_paid. See Credits and billing.
Async search
Section titled “Async search”A search for up to 10,000 jobs that runs in the background. Start it with POST /v1/searches, then poll GET /v1/searches/{id} or receive search.completed. Branch on its status: queued, running, completed, partial, failed or on_hold. See Async searches.
BetterJobs index
Section titled “BetterJobs index”BetterJobs’ own job sources: an owned crawl of employer career pages and ATSs. Slug betterjobs. Available on every plan, and searched first by cheapest_first. See BetterJobs index.
Canonical job
Section titled “Canonical job”One real opening, merged from every source that saw it. It has one stable id (job_...) no matter how many providers listed it or how often it was reposted. See Canonical jobs.
Consensus
Section titled “Consensus”A waterfall strategy that returns only jobs seen by at least min_sources sources (default 2). Fewer jobs, more confidence. See Choose a strategy.
Credit
Section titled “Credit”The billing unit. 1 credit = 1 unique job returned that you have not already paid for. Company profiles cost 1 credit each, and each job.opened a watch delivers costs 1 credit unless you already paid for that job. See Credits and billing.
Cursor
Section titled “Cursor”An opaque string that points to the next page. Pass next_cursor back as cursor. next_cursor: null means the last page. On GET /v1/events you pass it as since. See Pagination.
Dry run
Section titled “Dry run”A free estimate. Send "dry_run": true on POST /v1/jobs/search and get expected_unique_jobs_range, providers_planned and credits_range without fetching any jobs.
Duplicate
Section titled “Duplicate”A provider record that describes a job already in the results. BetterJobs merges it into the canonical job and adds it to sources[]. Duplicates are free. Counted in metadata.duplicates_merged.
A typed message about a change, such as job.opened or company.hiring_stopped. Delivered by webhook and readable from GET /v1/events. See Events.
Field coverage
Section titled “Field coverage”metadata.field_coverage: for each field, the fraction (0-1) of returned jobs that have a non-null value. It is measured on your actual results, per request. See Field dictionary.
First seen, last seen, last verified
Section titled “First seen, last seen, last verified”Three timestamps on every job. first_seen_at: earliest time any source saw it. last_seen_at: latest time any source saw it. last_verified_at: latest time it was confirmed live at its origin. posted_at is the employer’s own date, often unknown. See Freshness and lifecycle.
Hiring pulse
Section titled “Hiring pulse”hiring_pulse on a company profile: direction (up, flat, down) and open_jobs_30d_change. See Companies.
Idempotency key
Section titled “Idempotency key”The Idempotency-Key header on a POST. A retry with the same key and body returns the first response and never charges twice. The same key with a different body returns 409 idempotency_conflict. See Idempotency.
is_hiring
Section titled “is_hiring”A company’s hiring answer: value (true, false or null), confidence (0-1) and a plain-English basis. null means unknown. Never treat null as false. See field reference.
Ledger
Section titled “Ledger”GET /v1/billing/ledger: one entry per job per charge or free re-read, with the request_id that caused it. Your proof of what you paid for. See Credits and billing.
License
Section titled “License”license on every job. display: you may show the job to your end users. resale: you may resell or redistribute it as data. See Licensing.
max_credits
Section titled “max_credits”waterfall.max_credits: a hard cap on what one request may charge. Results stop at the cap.
on_hold
Section titled “on_hold”An async search status that means you ran out of credits. The search resumes after a top-up.
p_real
Section titled “p_real”The probability (0-1) that a job is a real open req, from how many independent sources corroborate it. See Provenance and confidence and the field reference.
Partial
Section titled “Partial”metadata.status: partial: at least one provider failed or missed timeout_ms. You still get 200, the other sources’ jobs, and you pay only for those. The failures are in metadata.providers.failed. See Provider status.
Partner provider
Section titled “Partner provider”One of the six third-party sources BetterJobs routes to: Reqbeat, SignalsAPI, TheirStack, JobsPipe, Coresignal and Techmap. Growth includes two, Pro and above include all six. See Providers.
Provenance
Section titled “Provenance”Where each part of a job came from. sources[] lists every provider that saw the job, its own id and URL, when it saw it, and which fields it contributed. See Provenance and confidence.
Provider
Section titled “Provider”Any source BetterJobs can route to: the six partner providers plus the BetterJobs index. Identified by its slug. GET /v1/providers lists them with live status.
Repost
Section titled “Repost”The same job listed again. BetterJobs keeps the same canonical id and raises repost_count. A watch sends job.reposted, which should never re-trigger outbound.
Sandbox
Section titled “Sandbox”POST /v1/sandbox/jobs/search: same request and response shape as the live search, no key, fixed illustrative data, nothing charged.
Strategy
Section titled “Strategy”waterfall.strategy: how BetterJobs picks and orders providers. One of cheapest_first (default), freshest_first, max_coverage, consensus, own_only. See Choose a strategy.
timeout_ms
Section titled “timeout_ms”waterfall.timeout_ms: the time budget for one request, 1,000 to 30,000 ms (default 10,000). Providers slower than this are dropped and the result is partial.
Unique job
Section titled “Unique job”A canonical job counted once, however many providers returned it. What a credit buys.
Version
Section titled “Version”The date in the BetterJobs-Version header, currently 2026-10-01. Changes inside a version are additive only. See Versioning.
A standing subscription to a company domain (type: company) or a saved filter (type: search). Matching events go to its webhook_url. Free to create. See Detect hiring changes.
Waterfall
Section titled “Waterfall”How BetterJobs runs one search across many providers: it asks them according to the strategy, merges what they return into canonical jobs, and removes duplicates. See Waterfall.
Webhook signature
Section titled “Webhook signature”The BetterJobs-Signature header on every delivery: t=<unix>,v1=<hex>. v1 is the HMAC-SHA256 of <t>.<raw body> with your endpoint secret. See Webhooks.