Jobs endpoints

List jobs

One result is a combined job_id with its associated postings. By default, results sort by job_updated_at descending, then job_id descending; text-search requests default to relevance, and sort=updated selects updated order explicitly. The REST page limit is at most 250, while the MCP search_jobs tool caps pages at 25. The response serializer is list-specific; see field shapes.

Count jobs

The count uses a distinct included-job count at a projection watermark. It is a separate request from list paging; a changing projection or query scope can make totals differ from a client’s accumulated pages.

curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs/count?company_id=12345678-1234-4234-8234-123456789abc&currentness=current" --header 'Authorization: Bearer <API_KEY>'

Read one job

The identifier is a canonical lowercase UUID for the combined job. A posting identifier and source posting identifier refer to different records. Detail serialization differs from list serialization.

curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs/12345678-1234-4234-8234-123456789abc" --header 'Authorization: Bearer <API_KEY>'

Read job changes

GET /v1/jobs/changes is available with an API key. Start with a since timestamp or continue with the opaque after cursor. The response contains data, resume_cursor, has_more, and snapshot_watermark; created and updated events can include a job, while expired events identify the job and event time. The route can return 503 if the projection is unavailable or changes during the request.

curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs/changes?after=opaque_cursor_example&limit=100" --header 'Authorization: Bearer <API_KEY>'

Request example

curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs?currentness=current&limit=50" --header 'Authorization: Bearer <API_KEY>'

The list response contains combined jobs and their postings.