Get an async search

Get an async search. Returns the search status and, once `completed` or `partial`, a page of results.

Cost: FreeFree. Jobs are charged when the search collects them, not when you read results.

GET

/searches/{id}

const url = 'https://api.betterjobs.cc/v1/searches/srch_2Vd9KqL4mN?cursor=cur_8fJ2kQ&limit=100';
const options = {
  method: 'GET',
  headers: {'BetterJobs-Version': '2026-10-01', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.betterjobs.cc/v1/searches/srch_2Vd9KqL4mN?cursor=cur_8fJ2kQ&limit=100' \
  --header 'Authorization: Bearer <token>' \
  --header 'BetterJobs-Version: 2026-10-01'

Returns the search status and, once completed or partial, a page of results. Page through results with cursor. Branch on status, not on the HTTP code. on_hold means you ran out of credits; the search resumes after a top-up.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

/^srch_/

Example

srch_2Vd9KqL4mN

Search id (srch_...).

Header Parameters

BetterJobs-Version

string

Allowed values: 2026-10-01

Example

2026-10-01

Date-pinned API version. Changes within a version are additive only. Defaults to your account’s pinned version.

Query Parameters

cursor

string

Example

cur_8fJ2kQ

Opaque cursor from a previous next_cursor.

limit

integer

default: 100 >= 1 <= 100

Results per page.

Responses

200

Search state.

application/json

Async search. Branch on status, not on the HTTP code.

object

required

string

/^srch_/

status

required

on_hold = out of credits; resumes after a top-up. partial = finished but at least one provider failed.

string

Allowed values: queued running completed partial failed on_hold

created_at

required

string format: date-time

updated_at

required

string format: date-time

completed_at

required

string | null format: date-time

webhook_url

required

string | null format: uri

jobs_found

required

Unique jobs collected so far.

integer

data

required

A page of results once completed or partial. Empty otherwise.

Array<object>

A canonical job: one real opening, merged from every source that saw it. Null semantics: null = unknown; [] = verified none; field omitted = not part of this payload (for example the lifecycle-only job in job.closed and job.reposted events).

object

required

Canonical job id. Stable across sources and requests.

string

/^job_/

title

required

string

company

required

Company reference embedded in jobs, events and profiles.

object

required

string

/^cmp_/

name

required

string

domain

required

Primary web domain. null when unknown.

string | null

location

required

object

city

required

string | null

region

required

string | null

country_code

required

ISO 3166-1 alpha-2.

string | null

remote

required

true remote, false on-site or hybrid, null unknown.

boolean | null

employment_type

required

One of:

string
null

string

Allowed values: full_time part_time contract internship temporary

seniority

required

One of:

string
null

string

Allowed values: intern junior mid senior lead director vp c_level

job_family

required

string | null

salary

required

One of:

object
null

object

min

required

number | null

max

required

number | null

currency

required

ISO 4217.

string

period

required

string

Allowed values: year month hour

origin

required

declared = stated in the posting. inferred = estimated by a source.

string

Allowed values: declared inferred

description

required

Plain-text job description.

string | null

apply_url

required

string | null format: uri

posted_at

required

Date the employer posted the job, if known.

string | null format: date-time

first_seen_at

required

Earliest time any source saw the job.

string format: date-time

last_seen_at

required

Latest time any source saw the job.

string format: date-time

last_verified_at

required

Latest time the job was confirmed live at its origin.

string | null format: date-time

status

required

string

Allowed values: open closed

closed_reason

required

Why the job closed. null while open.

string | null

Allowed values: filled expired removed unknown

repost_count

required

Times the same job was re-listed.

integer

p_real

required

Probability (0-1) that the job is a real open req, from cross-source corroboration.

number

<= 1

sources

required

Array<object>

One provider’s view of the canonical job.

object

provider

required

Source slug. betterjobs is the BetterJobs index.

string

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

provider_job_id

required

string

url

required

string | null format: uri

first_seen_at

required

string format: date-time

last_seen_at

required

string format: date-time

fields

required

Job fields this source contributed to the canonical record.

Array<string>

license

required

object

display

required

You may show this job to your end users.

boolean

resale

required

You may resell or redistribute this job as data.

boolean

next_cursor

required

string | null

metadata

required

One of:

object
null

object

request_id

required

string

status

required

partial = at least one provider failed or timed out. You are billed only for returned jobs.

string

Allowed values: complete partial

credits_charged

required

integer

jobs_already_paid

required

Returned jobs you had already paid for (free).

integer

duplicates_merged

required

Provider records merged into existing canonical jobs (free).

integer

credits_remaining

required

integer

providers

required

object

tried

required

Array<string>

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

hit

required

Providers that returned at least one match.

Array<string>

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

failed

required

Array<object>

object

provider

required

Source slug. betterjobs is the BetterJobs index.

string

Allowed values: betterjobs reqbeat signalsapi theirstack jobspipe coresignal techmap

code

required

provider_timeout = the provider missed timeout_ms. provider_error = the provider returned an error.

string

Allowed values: provider_timeout provider_error

contributions

required

Unique jobs each provider contributed first.

object

key

additional properties

integer

field_coverage

required

Fraction (0-1) of returned jobs with a non-null value, per field.

object

key

additional properties

number

<= 1

latency_ms

required

integer

Examples

Still running

{
  "id": "srch_2Vd9KqL4mN",
  "status": "running",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:01:30Z",
  "completed_at": null,
  "webhook_url": "https://hooks.northwind.example/betterjobs",
  "jobs_found": 1260,
  "data": [],
  "next_cursor": null,
  "metadata": null
}

Out of credits

{
  "id": "srch_2Vd9KqL4mN",
  "status": "on_hold",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:04:10Z",
  "completed_at": null,
  "webhook_url": "https://hooks.northwind.example/betterjobs",
  "jobs_found": 2210,
  "data": [],
  "next_cursor": null,
  "metadata": null
}

Completed with results

{
  "id": "srch_2Vd9KqL4mN",
  "status": "completed",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:06:45Z",
  "completed_at": "2026-10-11T09:06:45Z",
  "webhook_url": "https://hooks.northwind.example/betterjobs",
  "jobs_found": 3184,
  "data": [
    {
      "id": "job_01JC9F2K7NQ3XW5R8T1Y6M4H0C",
      "title": "Senior Data Engineer",
      "company": {
        "id": "cmp_2Lm8QwE5rT",
        "name": "Contoso Health",
        "domain": "contoso-health.example"
      },
      "location": {
        "city": "Amsterdam",
        "region": "North Holland",
        "country_code": "NL",
        "remote": true
      },
      "employment_type": "full_time",
      "seniority": "senior",
      "job_family": "engineering",
      "salary": null,
      "description": "Build and run the batch and streaming pipelines behind Contoso Health's clinical analytics.",
      "apply_url": "https://careers.contoso-health.example/jobs/4471",
      "posted_at": null,
      "first_seen_at": "2026-10-02T11:00:00Z",
      "last_seen_at": "2026-10-11T05:20:00Z",
      "last_verified_at": "2026-10-10T22:00:00Z",
      "status": "open",
      "closed_reason": null,
      "repost_count": 1,
      "p_real": 0.88,
      "sources": [
        {
          "provider": "jobspipe",
          "provider_job_id": "jp_77120983",
          "url": "https://careers.contoso-health.example/jobs/4471",
          "first_seen_at": "2026-10-02T11:00:00Z",
          "last_seen_at": "2026-10-11T05:20:00Z",
          "fields": [
            "title",
            "description",
            "apply_url",
            "location",
            "seniority",
            "employment_type"
          ]
        },
        {
          "provider": "coresignal",
          "provider_job_id": "cs_410298811",
          "url": "https://careers.contoso-health.example/jobs/4471",
          "first_seen_at": "2026-10-03T02:15:00Z",
          "last_seen_at": "2026-10-10T22:00:00Z",
          "fields": [
            "job_family"
          ]
        }
      ],
      "license": {
        "display": true,
        "resale": false
      }
    }
  ],
  "next_cursor": "cur_Lp0sR3",
  "metadata": {
    "request_id": "req_5Tg1HsW8cV",
    "status": "complete",
    "credits_charged": 3012,
    "jobs_already_paid": 172,
    "duplicates_merged": 1907,
    "credits_remaining": 6829,
    "providers": {
      "tried": [
        "betterjobs",
        "reqbeat",
        "signalsapi",
        "theirstack",
        "jobspipe",
        "coresignal",
        "techmap"
      ],
      "hit": [
        "betterjobs",
        "reqbeat",
        "signalsapi",
        "theirstack",
        "jobspipe",
        "coresignal",
        "techmap"
      ],
      "failed": [],
      "contributions": {
        "betterjobs": 1210,
        "reqbeat": 402,
        "signalsapi": 95,
        "theirstack": 610,
        "jobspipe": 388,
        "coresignal": 241,
        "techmap": 238
      }
    },
    "field_coverage": {
      "salary": 0.41,
      "seniority": 0.97,
      "location.remote": 0.88,
      "description": 0.99
    },
    "latency_ms": 405112
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

RateLimit-Limit

integer

Example

Requests allowed in the current window.

RateLimit-Remaining

integer

Example

Requests left in the current window.

RateLimit-Reset

integer

Example

Seconds until the window resets.

401

Missing or invalid API key.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error billing_error permission_error not_found_error conflict_error rate_limit_error api_error

code

required

string

Allowed values: invalid_request unknown_filter unauthorized insufficient_credits plan_required not_found idempotency_conflict rate_limited internal_error

message

required

string

doc_url

required

string format: uri

request_id

required

string

credits_needed

Present on insufficient_credits.

integer

required_plan

string

Allowed values: free starter growth pro scale enterprise

upgrade_url

Present on insufficient_credits and plan_required.

string format: uri

param

Offending field on invalid_request and unknown_filter.

string

key

additional properties

any

Examples

unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Missing or invalid API key. Send 'Authorization Bearer bj_live_...'.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#unauthorized",
    "request_id": "req_5Dl6EvN0xY"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

404

The resource does not exist.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error billing_error permission_error not_found_error conflict_error rate_limit_error api_error

code

required

string

Allowed values: invalid_request unknown_filter unauthorized insufficient_credits plan_required not_found idempotency_conflict rate_limited internal_error

message

required

string

doc_url

required

string format: uri

request_id

required

string

credits_needed

Present on insufficient_credits.

integer

required_plan

string

Allowed values: free starter growth pro scale enterprise

upgrade_url

Present on insufficient_credits and plan_required.

string format: uri

param

Offending field on invalid_request and unknown_filter.

string

key

additional properties

any

Examples

notFound

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "No job with id 'job_01JC00000000000000000000XX'.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#not_found",
    "request_id": "req_8Gi3HsK7uV"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

429

Too many requests. Wait Retry-After seconds.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error billing_error permission_error not_found_error conflict_error rate_limit_error api_error

code

required

string

Allowed values: invalid_request unknown_filter unauthorized insufficient_credits plan_required not_found idempotency_conflict rate_limited internal_error

message

required

string

doc_url

required

string format: uri

request_id

required

string

credits_needed

Present on insufficient_credits.

integer

required_plan

string

Allowed values: free starter growth pro scale enterprise

upgrade_url

Present on insufficient_credits and plan_required.

string format: uri

param

Offending field on invalid_request and unknown_filter.

string

key

additional properties

any

Examples

rateLimited

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#rate_limited",
    "request_id": "req_0Ig1JqH5sT"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

Retry-After

integer

Example

Seconds to wait before retrying.

RateLimit-Limit

integer

Example

Requests allowed in the current window.

RateLimit-Remaining

integer

Example

Requests left in the current window.

RateLimit-Reset

integer

Example

Seconds until the window resets.

500

Something failed on our side. Safe to retry with the same Idempotency-Key.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error billing_error permission_error not_found_error conflict_error rate_limit_error api_error

code

required

string

Allowed values: invalid_request unknown_filter unauthorized insufficient_credits plan_required not_found idempotency_conflict rate_limited internal_error

message

required

string

doc_url

required

string format: uri

request_id

required

string

credits_needed

Present on insufficient_credits.

integer

required_plan

string

Allowed values: free starter growth pro scale enterprise

upgrade_url

Present on insufficient_credits and plan_required.

string format: uri

param

Offending field on invalid_request and unknown_filter.

string

key

additional properties

any

Examples

internalError

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Unexpected error. Retry with the same Idempotency-Key; you will not be charged twice.",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#internal_error",
    "request_id": "req_1Jf0KpG4rS"
  }
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.