snapshots (paid per file)

POST /v1/snapshots/{stamp}/{file}

A 24-hour link to one snapshot file (`everything` or a country); the file's jobs are charged once

A link that lives 24 hours to one snapshot file: everything or a country as /v1/snapshots names it. The jobs in the file are charged at once against the plan (one usage row), so a plan too small for the file gets 429 plan_exhausted and nothing is charged. Load the snapshot, then read /v1/events from its seq.

Charged: the file's jobs, once, at link time; a second link for the same file inside 24 hours is free; the companies file comes free.

Parameters

An unknown parameter is a 400 bad_request. country and system take one value, a comma list (country=Canada,Mexico) or a repeat (country=Canada&country=Mexico); the country is its English name as the data holds it; the system is the ATS name (greenhouse, lever.co, workday, ...): /v1/jobs/count lists the sizes, /docs/sizes shows them.

Answer

{
 "stamp": "20261107-191824Z",
 "file": "canada",
 "jobs": 81137,
 "bytes": 190000000,
 "sha256": "...",
 "charged": 81137,
 "expires_at": "<time>",
 "link_id": "<uuid>",
 "companies": 2874,
 "url": "https://...",
 "companies_url": "https://..."
}

Example

curl -s -X POST https://api.jobmonkey.ai/v1/snapshots/20261107-191824Z/canada -H 'Authorization: Bearer cb_live_XXXXXXXX'

{
 "stamp": "20261107-191824Z",
 "file": "canada",
 "jobs": 81137,
 "bytes": 190000000,
 "sha256": "3b1f...",
 "charged": 81137,
 "expires_at": "2026-11-08T19:20:00Z",
 "link_id": "6f1e2d3c-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
 "companies": 2874,
 "url": "https://<signed link>",
 "companies_url": "https://<signed link>"
}

In Python

import json, urllib.request

KEY = "cb_live_XXXXXXXX"
req = urllib.request.Request("https://api.jobmonkey.ai/v1/snapshots/20261107-191824Z/canada", method="POST", headers={"Authorization": f"Bearer {KEY}"})
with urllib.request.urlopen(req) as r:
    answer = json.load(r)
    print(r.headers.get("X-Request-Id"), r.headers.get("X-Units-Charged"))
print(json.dumps(answer, indent=1)[:800])

Errors

• 401 no_key / bad_key / account_off
• 404 not_found (no such stamp or file)
• 429 rate_limited
• 429 plan_exhausted (the file holds more jobs than the plan has left)

Headers

• X-Request-Id
• X-Units-Charged
• RateLimit (limit=10, remaining=n, reset=s)
• RateLimit-Policy (10;w=1, plus 10;w=86400 on a free key calling a free route)
• X-Plan-Jobs-Remaining (the full feed and snapshots, when the plan has a cap)
• X-Account: past_due (while an invoice is unpaid)

Every answer carries X-Request-Id; quote it to [email protected]. Times are UTC, ISO 8601.