List events

List events. Event feed for your watches and async searches, oldest first.

Cost: FreeReading the feed is free. job.opened events are charged 1 credit when a watch delivers them.

GET

/events

const url = 'https://api.betterjobs.cc/v1/events?since=cur_E5vB7n&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/events?since=cur_E5vB7n&limit=100' \
  --header 'Authorization: Bearer <token>' \
  --header 'BetterJobs-Version: 2026-10-01'

Event feed for your watches and async searches, oldest first. Pass the next_cursor from the previous page as since to resume.

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

since

string

Example

cur_E5vB7n

Cursor from a previous next_cursor. Omit to start from the oldest retained event.

limit

integer

default: 100 >= 1 <= 100

Events per page.

Responses

200

A page of events.

application/json

object

data

required

Array<object>

Typed event envelope. data carries the objects relevant to type: job for job events, company and is_hiring for company events, search for search.completed.

object

required

string

/^evt_/

type

required

string

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

created_at

required

string format: date-time

watch_id

required

Watch that produced the event. null for search.completed.

string | null

data

required

object

job

Canonical job. Full Job for job.opened and job.updated; id, title, company, status and lifecycle fields otherwise.

object

company

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

is_hiring

object

value

required

null = unknown. Never treat null as false.

boolean | null

confidence

required

number

<= 1

basis

required

Plain-English reason for the value.

string

search

object

string

status

string

jobs_found

integer

next_cursor

required

Pass as since to resume.

string | null

Examples

feed

{
  "data": [
    {
      "id": "evt_7Wq1ZxC4vB",
      "type": "job.opened",
      "created_at": "2026-10-11T06:15:00Z",
      "watch_id": "wat_6Np3QyR8tU",
      "data": {
        "job": {
          "id": "job_01JC8X4M2Q7RV3T9KD5W6YH0AB",
          "title": "Head of Revenue Operations",
          "company": {
            "id": "cmp_4Rk7TzP1aQ",
            "name": "Acme Robotics",
            "domain": "acme-robotics.example"
          },
          "location": {
            "city": "Berlin",
            "region": "Berlin",
            "country_code": "DE",
            "remote": false
          },
          "employment_type": "full_time",
          "seniority": "lead",
          "job_family": "operations",
          "salary": {
            "min": 110000,
            "max": 135000,
            "currency": "EUR",
            "period": "year",
            "origin": "declared"
          },
          "description": "Acme Robotics is hiring a Head of Revenue Operations to own forecasting, CRM hygiene and the GTM tool stack across DACH.",
          "apply_url": "https://jobs.acme-robotics.example/revops-lead/apply",
          "posted_at": "2026-10-08T00:00:00Z",
          "first_seen_at": "2026-10-08T06:40:00Z",
          "last_seen_at": "2026-10-11T06:10:00Z",
          "last_verified_at": "2026-10-11T06:10:00Z",
          "status": "open",
          "closed_reason": null,
          "repost_count": 0,
          "p_real": 0.94,
          "sources": [
            {
              "provider": "betterjobs",
              "provider_job_id": "bj_idx_5521907",
              "url": "https://jobs.acme-robotics.example/revops-lead",
              "first_seen_at": "2026-10-08T06:40:00Z",
              "last_seen_at": "2026-10-11T06:10:00Z",
              "fields": [
                "title",
                "description",
                "apply_url",
                "location",
                "employment_type",
                "posted_at"
              ]
            }
          ],
          "license": {
            "display": true,
            "resale": false
          }
        }
      }
    },
    {
      "id": "evt_3Fh8JkL2pQ",
      "type": "job.reposted",
      "created_at": "2026-10-11T07:30:00Z",
      "watch_id": "wat_6Np3QyR8tU",
      "data": {
        "job": {
          "id": "job_01JC2B7Y9MZQ4W8E1R6T3N5K0D",
          "title": "Senior Robotics Engineer",
          "company": {
            "id": "cmp_4Rk7TzP1aQ",
            "name": "Acme Robotics",
            "domain": "acme-robotics.example"
          },
          "status": "open",
          "repost_count": 2
        }
      }
    }
  ],
  "next_cursor": "cur_E5vB7n"
}

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.

400

Invalid request (invalid_request) or unknown filter field (unknown_filter).

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

unknown_filter

{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_filter",
    "message": "Unknown filter field 'job_title_or'. Did you mean 'title_or'?",
    "param": "filters.job_title_or",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#unknown_filter",
    "request_id": "req_4Bn8CxV2zA"
  }
}

invalid_request

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "limit must be between 1 and 100.",
    "param": "limit",
    "doc_url": "https://docs.betterjobs.cc/platform/errors/#invalid_request",
    "request_id": "req_2Cm7DwB1yZ"
  }
}

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.