> ## 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 Summary

> Current billing-period usage: plan, subscription status, and per-meter allowances

Returns your current billing period's usage across every meter — what you've used, what your plan includes, what's remaining, and any overage. Calls to this endpoint are **not metered** and don't count against any allowance.

<Warning>
  Requires authentication (API key or JWT).
</Warning>

## Endpoint

```bash theme={null}
GET /v2/billing/usage/summary
```

## Response

<ResponseField name="billing_source" type="string">
  `"stripe_v2"` for accounts on the current plan catalog; `"legacy"` for grandfathered accounts (whose meters show `null` allowances)
</ResponseField>

<ResponseField name="stripe_customer_id" type="string | null">
  Your Stripe customer ID
</ResponseField>

<ResponseField name="plan_lookup_keys" type="string[]">
  Active plan identifiers (e.g. `["plan_starter"]`)
</ResponseField>

<ResponseField name="subscription_status" type="string | null">
  Stripe subscription status (e.g. `"active"`)
</ResponseField>

<ResponseField name="period_start" type="string | null">
  ISO timestamp of the current billing period start. `null` for accounts with no subscription (free tier), whose allowances reset on the first of each calendar month (UTC). Trial accounts see the trial window.
</ResponseField>

<ResponseField name="period_end" type="string | null">
  ISO timestamp of the current billing period end (`null` on the free tier, see above)
</ResponseField>

<ResponseField name="meters" type="array">
  One entry per meter, sorted alphabetically

  <Expandable>
    <ResponseField name="event_name" type="string">
      Meter key — one of `m_jobs_api_calls`, `m_company_api_calls`, `m_insights_calls`, `m_salary_benchmarks`, `m_hiring_manager_contacts`. Everything that returns jobs (search, vector, neural, company jobs, exports) rolls into `m_jobs_api_calls`.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      Human-readable meter name
    </ResponseField>

    <ResponseField name="used" type="integer">
      Units used this period
    </ResponseField>

    <ResponseField name="included" type="integer | null">
      Units included in your plan
    </ResponseField>

    <ResponseField name="remaining" type="integer | null">
      `max(0, included - used)`
    </ResponseField>

    <ResponseField name="overage_used" type="integer">
      Units used beyond the included allowance
    </ResponseField>

    <ResponseField name="overage_mode" type="string | null">
      `"block"` — requests return `429` once `included` is exhausted. `"meter"` — requests continue and overage is billed.
    </ResponseField>

    <ResponseField name="overage_cents_per_unit" type="integer | null">
      Overage price in cents per `overage_unit` units (metered mode only)
    </ResponseField>

    <ResponseField name="estimated_overage_cents" type="integer">
      Estimated overage charge so far this period
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Every metered API response also carries [`Hirebase-Usage-*` headers](/docs/api-reference/billing/usage-headers) with the same numbers for the meter that request billed — use those to track quota without polling this endpoint.
</Tip>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl 'https://api.hirebase.org/v2/billing/usage/summary' \
    -H 'x-api-key: YOUR_API_KEY'
  ```
</CodeGroup>

<ResponseExample>
  ```json Response (truncated) theme={null}
  {
    "billing_source": "stripe_v2",
    "plan_lookup_keys": ["plan_starter"],
    "subscription_status": "active",
    "period_start": "2026-08-02T13:16:47",
    "period_end": "2026-09-02T13:16:47",
    "meters": [
      {
        "event_name": "m_jobs_api_calls",
        "display_name": "Jobs",
        "used": 3,
        "included": 25000,
        "remaining": 24997,
        "overage_used": 0,
        "period": "month",
        "overage_mode": "block",
        "estimated_overage_cents": 0,
        "overage_currency": "usd"
      }
    ]
  }
  ```
</ResponseExample>