Get the billing ledger

Get the billing ledger. Proof of charge.

Cost: FreeFree.

GET

/billing/ledger

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

Proof of charge. Each entry shows when a job was charged, by which request, and for how many credits. Re-reads of a job you already paid for appear with credits: 0.

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

job_id

string

/^job_/

Example

job_01JC8X4M2Q7RV3T9KD5W6YH0AB

Only entries for this canonical job id.

cursor

string

Example

cur_8fJ2kQ

Opaque cursor from a previous next_cursor.

Responses

200

Ledger entries, newest first.

application/json

object

data

required

Array<object>

object

required

string

/^led_/

job_id

required

string

/^job_/

request_id

required

string

operation

required

Method and path, for example POST /v1/jobs/search.

string

credits

required

Credits charged. 0 for re-reads.

integer

reason

required

already_paid = re-read of a job you paid for earlier.

string

Allowed values: charged already_paid

created_at

required

string format: date-time

next_cursor

required

string | null

Examples

oneJob

One charge, then two free re-reads

{
  "data": [
    {
      "id": "led_0Zc5XvB9nM",
      "job_id": "job_01JC8X4M2Q7RV3T9KD5W6YH0AB",
      "request_id": "req_1Mn4BvC7xZ",
      "operation": "GET /v1/jobs/{id}",
      "credits": 0,
      "reason": "already_paid",
      "created_at": "2026-10-11T12:40:00Z"
    },
    {
      "id": "led_8Yb4WuA3mL",
      "job_id": "job_01JC8X4M2Q7RV3T9KD5W6YH0AB",
      "request_id": "req_6Lk3AzX2wY",
      "operation": "POST /v1/jobs/search",
      "credits": 0,
      "reason": "already_paid",
      "created_at": "2026-10-11T11:05:00Z"
    },
    {
      "id": "led_2Xa3VtZ1kK",
      "job_id": "job_01JC8X4M2Q7RV3T9KD5W6YH0AB",
      "request_id": "req_7Hc2LmQ9xT",
      "operation": "POST /v1/jobs/search",
      "credits": 1,
      "reason": "charged",
      "created_at": "2026-10-11T09:12:00Z"
    }
  ],
  "next_cursor": null
}

Headers

X-Request-Id

string

Example

req_7Hc2LmQ9xT

Unique id for this request. Quote it to support.

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.