Response headers

Read rate-limit, billing, pagination, and diagnostic state from these headers without parsing the body.

Rate limiting

Sent on every response to a request that counts toward an API key’s rate limits, sandbox keys included. Absent on an idempotent replay and on GET /api/companies/{id}, which needs no key and is not rate limited.

Header	Meaning
`X-RateLimit-Limit`	The request limit of the window being reported: the per-minute window on a success, the exhausted window on a `429`.
`X-RateLimit-Remaining`	Requests left in that window. Never negative.
`X-RateLimit-Used`	Requests already counted in that window.
`X-RateLimit-Reset`	`429` only. Unix epoch seconds when the exhausted window resets, sent alongside `Retry-After`.
`X-RateLimit-Group`	The rate-limit group whose budget applied: `Default`, `JobSearch`, `JobFeed`, `Geocode`, `DataSets`, `AutoApply`, or `AutoApplyManagement`.
`Retry-After`	Seconds to wait before retrying, on `429` and `503`. On a `202` from `GET /api/companies/by-domain` or its status poll, the suggested poll interval.

Wallet and job settlement

Sent when wallet or included-jobs settlement applies. Free endpoints omit them, and responses that deliver no jobs may omit them.

Header	Meaning
`X-Credits-Deducted`	Credits charged to the wallet for this response. `0` when your included jobs cover every delivered job. Absent when the Unlimited plan covers the product.
`X-Credits-Balance`	Your wallet balance in credits after the debit, or at the failed check on a `402`.
`X-Credits-Required`	`402` only. Credits the request needed to succeed.
`X-Billing-Status`	Rare. `Unconfirmed` means the jobs were delivered but wallet settlement could not be confirmed. Do not replay an `Unconfirmed` page automatically.

Credits convert at 1,000 credits = $1.00. Included-job use shows in X-Quota-Remaining, not X-Credits-Deducted. See Billing for when the wallet is checked and debited.

Included jobs

Sent on Search and Feed responses when a Job Search plan’s included jobs apply. The X-Quota-* names are historical.

Header	Meaning
`X-Quota-Limit`	Your plan’s included jobs for the billing month.
`X-Quota-Remaining`	Included jobs left this billing month after this response.

Page-based pagination

Sent on GET /api/jobs, POST /api/jobs/search, and GET /api/companies/{id}/jobs. See Pagination for request parameters and limits.

Header	Meaning
`X-Total-Count`	Total matching records across all pages.
`X-Total-Pages`	Total number of pages at the current `page_size`.
`X-Page`	The page returned. A page past the 100,000-result search depth is clamped to the last reachable page, and this header reports the clamped page.
`X-Page-Size`	The page size used.

Cursor pagination

Sent on POST /api/jobs/feed, POST /api/jobs/feed/managed, POST /api/jobs/feed/{feed_id}, and GET /api/jobs/expired.

Header	Meaning
`X-Has-More`	`True` when another page is available through `next_cursor` in the body, otherwise `False`. Compare case-insensitively, or read `has_more` from the body.

Idempotency

Header	Meaning
`X-Idempotent-Replay`	`true` on a stored replay; absent on a fresh execution. A replay carries only the original status and body, not its other headers.

See Idempotency for the full contract.

Endpoint-specific headers

Header	Sent on	Meaning
`X-Jobo-Warnings`	`GET /api/jobs`, `POST /api/jobs/search`, and the first page of `POST /api/jobs/feed`	Comma-separated warning codes, such as `unknown_request_fields` or `companies_unmatched`, sent only when there is something to report. The body’s `warnings` array has the same codes.
`X-Feed-Revision`	`POST /api/jobs/feed/{feed_id}`	The saved feed’s content revision, also returned as `feed_revision`.
`X-Jobo-Profile-Cache`	`GET /api/companies/by-domain` and its status poll	`hit`, `stale` (served past its cache period), or `miss`.
`Location`	A `202` from `GET /api/companies/by-domain` or its status poll	The status URL to poll, sent with `Retry-After`.
`X-Jobo-Environment`	Every response to a sandbox key	Always `sandbox`. See Sandbox.
`X-RapidAPI-Billing`	Requests through the RapidAPI marketplace only	Not part of the direct `connect.jobo.world` contract. Ignore it unless you call through RapidAPI.

Diagnostics

Header	Sent on	Meaning
`x-correlation-id`	Every response	The ID to quote in support requests. See Errors.
`WWW-Authenticate`	`401` only	`ApiKey realm="api.jobo.world"`. The realm is a label, not a hostname: always call `https://connect.jobo.world`.

Caching

Header	Sent on	Meaning
`Cache-Tag`	`GET /api/companies/{id}`	An opaque tag used for targeted CDN invalidation when the company record changes.
`Cloudflare-CDN-Cache-Control`	`GET /api/companies/{id}`	The CDN TTL: 90 days on a hit, 60 seconds on a `404`.
`Cache-Control: no-store`	`GET /api/companies/{id}`, `GET /api/companies/by-domain` and its status poll	Tells browsers not to store the response. By-domain responses are never CDN-cached either.
`Cache-Control: private, max-age=30`	`GET /api/jobs/expired`	Lets your client reuse the response for up to 30 seconds.

Worked example

A search response on the Starter plan. Included jobs cover all 25 delivered jobs, so the wallet is not charged:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Used: 2
X-RateLimit-Group: JobSearch
X-Quota-Limit: 200000
X-Quota-Remaining: 199975
X-Credits-Deducted: 0
X-Total-Count: 214
X-Total-Pages: 9
X-Page: 1
X-Page-Size: 25
x-correlation-id: 989f012bca1b4a0a994aa583efaa8f5d

Overview

Conventions

Jobs

Feed

Companies

Locations

Auto Apply

Rate limiting

Wallet and job settlement

Included jobs

Idempotency

Endpoint-specific headers

Diagnostics

Caching

Worked example

​Rate limiting

​Wallet and job settlement

​Included jobs

​Page-based pagination

​Cursor pagination

​Idempotency

​Endpoint-specific headers

​Diagnostics

​Caching

​Worked example

Rate limiting

Wallet and job settlement

Included jobs

Page-based pagination

Cursor pagination

Idempotency

Endpoint-specific headers

Diagnostics

Caching

Worked example