List watches

List watches.

Cost: FreeFree.

GET

/watches

const url = 'https://api.betterjobs.cc/v1/watches?cursor=cur_8fJ2kQ';
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/watches?cursor=cur_8fJ2kQ' \
  --header 'Authorization: Bearer <token>' \
  --header 'BetterJobs-Version: 2026-10-01'

Authorizations

bearerAuth

Parameters

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.

Responses

200

Your watches.

application/json

object

data

required

Array<object>

object

required

string

/^wat_/

type

required

string

Allowed values: company search

domain

required

string | null

filters

required

One of:

object
null

Filter grammar with suffix operators. Unknown fields return 400 unknown_filter.

object

title_or

Match any of these title keywords.

Array<string>

title_not

Exclude titles containing any of these.

Array<string>

country_code_or

ISO 3166-1 alpha-2 codes.

Array<string>

posted_within_days

Jobs first seen within this many days.

integer

>= 1 <= 365

seniority_or

Array<string>

Allowed values: intern junior mid senior lead director vp c_level

employment_type_or

Array<string>

Allowed values: full_time part_time contract internship temporary

remote

true remote only, false non-remote only, null or omitted = any.

boolean | null

salary_min_gte

Keep jobs whose salary.min is at least this value (yearly, in the job’s currency). Jobs with salary null are excluded when set.

number

company_domain_or

Array<string>

job_family_or

Array<string>

include_closed

Include jobs with status: closed.

boolean

webhook_url

required

string format: uri

events

required

Array<string>

Allowed values: job.opened job.reposted job.closed job.updated company.hiring_started company.hiring_stopped search.completed

status

required

string

Allowed values: active paused

created_at

required

string format: date-time

next_cursor

required

string | null

Examples

list

{
  "data": [
    {
      "id": "wat_6Np3QyR8tU",
      "type": "company",
      "domain": "acme-robotics.example",
      "filters": null,
      "webhook_url": "https://hooks.northwind.example/betterjobs",
      "events": [
        "job.opened",
        "job.closed",
        "company.hiring_started",
        "company.hiring_stopped"
      ],
      "status": "active",
      "created_at": "2026-10-11T08:00:00Z"
    }
  ],
  "next_cursor": null
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

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.

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.