Get started with Headcount Labs

1. Choose one useful result

Start with a small task: find a page of roles, count matching jobs, or inspect one known combined job ID. Write down the title, region, source needs and required fields. The jobs reference explains which route supports each task; filter support can differ between list and count routes. The public sample explorer is useful for inspecting dated source snapshots without an account.

2. Open your account and create a key

Create an account or sign in on the separate API host, then open API key management. Create an API key there; you send it as a bearer token. Your plan sets your monthly job and request allowance; see pricing.

3. Prepare a safe request environment

Use your own server or protected terminal, with credentials kept server-side. Set HEADCOUNTLABS_BASE_URL to https://api.headcountlabs.com. The request below contains a placeholder, not a usable key. Replace it only in your protected environment with a credential issued for your account; check authentication first. This public website never asks you to enter a key and does not run API requests for you. Never send a password or API key by email, in a URL, or through the contact form.

4. Request a page of jobs

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

Set HEADCOUNTLABS_BASE_URL to https://api.headcountlabs.com and replace <API_KEY> with your credential. A request without a valid key returns JSON 401.

5. Check the response before continuing

{
  "data": [{
    "job_id": "12345678-1234-4234-8234-123456789abc",
    "currentness": "current",
    "stale": false,
    "company_id": null,
    "employer_name": {"state": "known", "value": "Unmatched employer"},
    "title": {"state": "known", "value": "Engineer"},
    "description": {"state": "source_unmapped", "value": null, "evidence": ["source label"]},
    "work_arrangement": {"state": "source_omitted"},
    "locations": [],
    "job_first_seen_at": "2026-09-20T00:00:00.000Z",
    "curated_at": "2026-09-21T00:00:00.000Z",
    "job_updated_at": "2026-09-23T12:00:00.000Z",
    "postings": [{
      "posting_id": "posting-1",
      "source": "greenhouse/example",
      "source_posting_id": "src-1",
      "posting_status": "listed",
      "posting_url": {"state": "known", "value": "https://jobs.invalid/1"},
      "application_url": {"state": "source_omitted"},
      "location": {"state": "source_omitted"},
      "pay": {"state": "source_omitted"},
      "source_posted_at": null,
      "first_seen_at": "2026-09-20T00:00:00.000Z",
      "last_completed_fetch_at": null,
      "latest_application_check": null
    }]
  }],
  "next_cursor": null,
  "snapshot_watermark": "2026-09-23T12:00:00.000Z"
}

Check the HTTP status and content type before reading data. A successful empty data array is different from an error. Keep field states such as source_omitted distinct from a known value. Follow a returned cursor according to the pagination guide; do not invent a next cursor. The posting follows the list DTO. Detail responses add attribution to each posting; see the field reference.

6. Troubleshoot without sharing secrets

For 401, check that you sent a valid bearer key to the intended API host. For 403, confirm the account entitlement. For 429, follow returned retry guidance and the account policy rather than repeatedly retrying. A 503 can indicate unavailable source data or a service dependency. Route-specific meanings and recovery details are in errors and response headers.

If you need help, prepare a support email to support@headcountlabs.com. Include the method and path, UTC time, status code, request ID if present, and redacted error text. Remove the Authorization header, credentials and private record content. The contact form opens a draft in your email app; you review it and choose whether to send. It does not submit a ticket or confirm delivery.

Choose the route that matches the task

Jobs covers combined job records, counts, detail, and a changes feed. Companies covers the company registry and company job listing. Usage reports describe request and returned-record reporting.