> ## Documentation Index
> Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage Headers & Metering
> What each endpoint costs, what every plan includes, and how to track quota from response headers
Every metered API response includes `Hirebase-Usage-*` headers describing the meter that request billed — so you can track quota consumption in real time without polling [Usage Summary](/docs/api-reference/billing/usage-summary) after every call. All of these headers (plus `X-Billing-Code` and the `X-RateLimit-*` set) are CORS-exposed for browser clients.
## Meters
Usage is metered by **what a response returns**, not by which endpoint you called. Every route that returns jobs bills the jobs meter; every route that returns companies bills the companies meter.
| Meter | Unit | Counts |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `m_jobs_api_calls` | jobs | Every job record returned by search, detail, company-jobs, vector, neural, and export endpoints |
| `m_company_api_calls` | companies | Every company record returned by company search and company detail |
| `m_insights_calls` | calls | One per insights request |
| `m_salary_benchmarks` | requests | One per salary benchmark request |
| `m_hiring_manager_contacts` | contacts | One per contact resolved |
## Headers
| Header | Meaning |
| ----------------------------------- | ------------------------------------------------------------------- |
| `Hirebase-Usage-Feature` | Feature the route belongs to (e.g. `jobs_api`) |
| `Hirebase-Usage-Meter` | Meter billed (e.g. `m_jobs_api_calls`) |
| `Hirebase-Usage-Unit` | Billing unit (`jobs`, `companies`, `calls`, `requests`, `contacts`) |
| `Hirebase-Usage-Included-Limit` | Your plan's included allowance for the meter |
| `Hirebase-Usage-Included-Used` | Included units consumed this period |
| `Hirebase-Usage-Included-Remaining` | Included units left this period |
| `Hirebase-Usage-Overage-Used` | Units consumed beyond the included allowance |
| `Hirebase-Usage-Overage-Mode` | `block` (429 at cap) or `meter` (overage billed) |
| `Hirebase-Usage-Total-Used` | Total period usage **including the current request** |
| `Hirebase-Usage-Period-Start` | Billing period start (UTC) |
| `Hirebase-Usage-Period-End` | Billing period end (UTC) |
Headers appear on successful responses **and** on quota `429`s (which additionally carry `X-Billing-Code: limit_exceeded`). They are absent on un-metered endpoints (billing, tasks, reference data) and on legacy-billing accounts.
Accounts without a subscription have no Stripe billing period, so `Period-Start`/`Period-End` are omitted and [Usage Summary](/docs/api-reference/billing/usage-summary) returns `null` for them. Free-tier allowances reset on the first of each calendar month (UTC). Trial accounts see the trial window as their period.
## What each endpoint costs
Meter costs apply to API-key calls. Web-app (dashboard) browsing costs 0 against these meters.
| Endpoint | Meter | Cost per call |
| --------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
| `POST /v2/jobs/search` | `m_jobs_api_calls` | **1 per job returned** |
| `GET /v2/jobs/{job_id}` | `m_jobs_api_calls` | 1 |
| `POST /v2/jobs/estimate` | `m_jobs_api_calls` | **0** — sizing a query is free and still works at the cap |
| `POST /v2/jobs/vsearch` | `m_jobs_api_calls` | 1 per job returned |
| `POST /v2/jobs/neural-search` | `m_jobs_api_calls` | 1 per job returned |
| `POST /v2/jobs/export` | `m_jobs_api_calls` | `min(limit, matching jobs)`, charged when the task is created; refunded if the task fails |
| `GET /v2/jobs/expired-jobs` | `m_jobs_api_calls` | **0** — the feed returns identifiers only |
| `POST /v2/jobs/expired-jobs/export` | `m_jobs_api_calls` | **0** — expired data is not billed; only live job data is |
| `GET /v2/hirebase/companies/{slug}/jobs` | `m_jobs_api_calls` | 1 per job returned |
| `GET /v2/hirebase/companies/{slug}/jobs/{job_slug}` | `m_jobs_api_calls` | 1 |
| `POST /v2/hirebase/companies/search` | `m_company_api_calls` | 1 per company returned |
| `GET /v2/hirebase/companies/{slug}` | `m_company_api_calls` | 1 |
| `POST /v2/jobs/insights` | `m_insights_calls` | 1 |
| `POST /v2/hirebase/companies/{slug}/insights` | `m_insights_calls` | 1 |
| `POST /v2/jobs/salary-benchmark` | `m_salary_benchmarks` | 1 |
| `POST /v2/jobs/contacts` | `m_hiring_manager_contacts` | 1 per contact returned |
| `POST /v2/embed` | — | Not metered (requires the `vector_api` feature) |
**Search calls bill per result, not per request.** A `POST /v2/jobs/search` with `limit: 100` that returns 100 jobs consumes 100 units of `m_jobs_api_calls`. The default `limit` is 10. On the free plan, five calls at `limit: 100` use the entire month's allowance — keep `limit` small while you evaluate.
## What each plan includes
Allowances reset every billing period. `block` means requests on that meter return `429` once the allowance is used; `meter` means requests keep succeeding and the extra units are billed at the overage rate.
| Plan | Jobs / month | Companies / month | Insights / month | Salary benchmarks / month |
| --------------------------- | -------------------------------- | --------------------------- | ----------------------- | ------------------------- |
| **Free** | 500, block | 50, block | 25, block | 3, block |
| **Starter** (\$99/mo) | 25,000, block | 10,000, block | 25, then \$10 per 1,000 | 25, then \$0.25 each |
| **Growth** (\$249/mo) | 250,000, then \$1.50 per 1,000 | 50,000, then \$5 per 1,000 | 25, then \$10 per 1,000 | 25, then \$0.25 each |
| **Scale** (\$999/mo) | 2,000,000, then \$1.50 per 1,000 | 200,000, then \$5 per 1,000 | 25, then \$10 per 1,000 | 25, then \$0.25 each |
| **Pro** (web plan, \$50/mo) | 10,000, then \$1 per 1,000 | 2,000, block | 25, then \$10 per 1,000 | 500, then \$0.05 each |
| **Enterprise** | Negotiated | Negotiated | Negotiated | Negotiated |
Every plan, including Free, can call every job, company, vector, export, and insights endpoint. Plans differ only in allowance and in what happens past it. Annual billing is 20% off the monthly price.
## At the cap
When a meter with `Overage-Mode: block` reaches its included allowance, further requests on that meter return `429` with `X-Billing-Code: limit_exceeded`:
```json theme={null}
{ "detail": "You've reached your plan's included usage of 25000 for this period. Upgrade at /v2/billing/portal to continue." }
```
The check is made **before** your request runs, using the most it could cost — the requested `limit` for per-result endpoints. If that does not fit in what remains, the request is refused and the message tells you how many units are left:
```json theme={null}
{ "detail": "This request could use up to 100 jobs but only 2 of your plan's included 500 remain this period. Lower `limit` or upgrade at /v2/billing/portal." }
```
Lower `limit` to the remaining count and the request succeeds. Because the reservation is atomic, parallel requests cannot overshoot a hard cap; each one either fits or is refused. Zero-cost endpoints such as `POST /v2/jobs/estimate` keep working at the cap.
Other meters are unaffected: a key that has used its jobs allowance can still search companies until the companies allowance is used.
Meters with `Overage-Mode: meter` keep returning `200` past the allowance; `Hirebase-Usage-Overage-Used` starts counting and overage is billed at your plan's rate. See [Error Handling](/docs/api-reference/errors) for distinguishing quota 429s from rate-limit 429s.
Read `Hirebase-Usage-Included-Remaining` on each response and size your next `limit` to it. The [Python SDK](/docs/sdk#tracking-quota-without-polling) exposes this as `client.last_usage` and raises `QuotaExceededError` for cap 429s so you never retry them as if they were rate limits.