> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusha.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor account usage with GET /v3/account/usage

> Get a full snapshot of your account: credit balance, rate limits, plan details, and per-action credit pricing - all in a single call.

The account usage endpoint gives you a real-time view of your entire account status in one call: your credit balance, your rate-limit usage across every time window, your plan details, and the current credit price of every billable action. Use it to stay ahead of plan limits, reconcile billing, and drive alerting in production pipelines.

**Endpoint:** `GET https://api.lusha.com/v3/account/usage`

<Warning>
  This endpoint has its own rate limit - **5 requests per minute** - lower than most other V3 endpoints. Do not poll it on every API call; fetch it on a schedule or before starting a large batch job.
</Warning>

## Example request

```bash theme={null}
curl --request GET \
  --url https://api.lusha.com/v3/account/usage \
  --header 'api_key: YOUR_API_KEY'
```

## Example response

```json theme={null}
{
  "credits": {
    "total": 10000,
    "used": 1500,
    "remaining": 8500
  },
  "rateLimits": {
    "daily": {
      "limit": 5000,
      "used": 120,
      "remaining": 4880,
      "resetsAt": "2026-03-31T00:00:00.000Z"
    },
    "hourly": {
      "limit": 500,
      "used": 20,
      "remaining": 480,
      "resetsAt": "2026-03-30T15:00:00.000Z"
    },
    "minute": {
      "limit": 25,
      "used": 1,
      "remaining": 24,
      "resetsAt": "2026-03-30T14:31:00.000Z"
    }
  },
  "plan": {
    "category": "professional",
    "renewalType": "annual",
    "startDate": "2026-01-01T00:00:00.000Z",
    "endDate": "2027-01-01T00:00:00.000Z"
  },
  "pricing": {
    "api_search": { "credits": 1, "perQuantity": 1 },
    "reveal_company": { "credits": 1, "perQuantity": 1 },
    "email": { "credits": 1, "perQuantity": 25 },
    "phone": { "credits": 5, "perQuantity": 1 }
  }
}
```

The response has four top-level sections:

| Section      | Description                                                                                                                                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credits`    | Your account-wide credit balance: `total`, `used`, and `remaining` for the current period.                                                                                                                                            |
| `rateLimits` | Your usage against the `daily`, `hourly`, and `minute` rate-limit windows. Any window can be `null` if it doesn't apply to your plan. Each populated window reports `limit`, `used`, `remaining`, and `resetsAt`.                     |
| `plan`       | Your plan `category`, `renewalType`, and the `startDate`/`endDate` of the current term.                                                                                                                                               |
| `pricing`    | A map of billing action name to `{ credits, perQuantity }` - the current credit cost of every billable action on your plan (for example, `api_search`, `reveal_company`, lookalikes, signals, and per-data-point contact enrichment). |

<Note>
  This is a significant shape change from the pre-V3 endpoint, which returned only a flat `usage` object keyed by credit type. If you have code that reads `response.usage.bulkCredits`, update it to read `response.credits`, `response.rateLimits`, `response.plan`, and `response.pricing` instead.
</Note>

## Use cases

* **Monitor consumption** - track `credits.used` over time to understand which workflows burn through credits fastest.
* **Avoid plan limit interruptions** - check `credits.remaining` before starting a large prospecting or enrichment job, and split or defer the job if it's running low.
* **Track rate-limit headroom** - check `rateLimits` before a batch run instead of guessing, or in addition to reading the `x-rate-limit-*` response headers documented in [Rate Limiting](/rate-limiting).
* **Support billing reconciliation** - pull `plan` and `pricing` at the end of a billing period to cross-check against your invoice.
* **Price out a workflow before running it** - look up the relevant key in `pricing` to estimate the credit cost of a batch job before you run it.

## Recommendations for production use

* **Poll on a schedule, not per request** - Fetch usage once per hour or at the start of each pipeline run rather than after every individual API call. This keeps you well within the 5 requests/minute rate limit.
* **Set a low-credit alert threshold** - When `credits.remaining` drops below a threshold meaningful to your workflow (for example, 10% of `credits.total`), trigger an alert or pause automated jobs to avoid unexpected failures.
* **Log usage before large batch jobs** - Record `credits.remaining` before and after a large batch run to confirm expected credit consumption and catch any anomalies early.

<Tip>
  If you run Lusha integrations across multiple systems or teams, designate one service to own usage polling and share the result with your other systems. This prevents each system from hitting the 5-requests-per-minute limit independently.
</Tip>

## API reference

<Card title="GET /v3/account/usage" icon="chart-bar" href="/api-reference/account/usage">
  Full field-by-field reference, error codes, and example response.
</Card>