---
title: "Usage API Reference | Leadsets Docs"
description: "GET /v1/usage: what's left in every Leadsets meter and when each window resets, as used and limit pairs. Free to call, works with read-only keys."
canonical: https://www.leadsets.ai/docs/api/usage
updated: 2026-11-11
---

REST API / Usage

# Get usage

What's left in every meter and when each window resets, so your agent can pace a run. Free to call.

GET /v1/usage MCP: get_usage

Records

None

Requests

Not counted

Keys

Works with read-only keys

## Parameters

None.

## Response

`plan`, then one block per meter. Each meter is a `[used, limit]` pair.

- Paid plans: `enrich` and `search`, each with `records_5h`, `requests_5h` and `records_week`, plus `resets_at` (when the oldest usage leaves the five-hour window) and `week_resets_at`. Both are null while the window is empty.
- Free plan: `free` with `search_records`, `enrich_records` and `data_calls`, plus `search_per_call` (10). Free records are one-time and never refill.
- Team and Max: `personal_emails_week`.
- Every plan: `concurrent_searches` as `[running, limit]`, `scrape_units` (your balance) and `scraping` (whether the plan can scrape).

Free plan response:

```
{
 "plan": "free",
 "free": {
   "search_records": [40, 100],
   "enrich_records": [212, 1000],
   "data_calls": [96, 1000],
   "search_per_call": 10,
   "note": "Free records are one-time and never refill."
 },
 "concurrent_searches": [0, 3],
 "scrape_units": 0,
 "scraping": false,
 "usage": {},
 "request_id": "req_0c7e3a9d4b21"
}
```

**Pace from the response, too.** Every data call already returns a `usage` object and X-Leadsets-*-Remaining headers, so most agents only need this route at the start of a run. See [Limits and costs](https://www.leadsets.ai/docs/limits).

## Errors

| Status | type | Meaning |
| --- | --- | --- |
| `401` | `unauthorized` | Missing, invalid, expired or revoked key. See [Authentication](https://www.leadsets.ai/docs/authentication). |

[Previous
**← GET /jobs/{id}**](https://www.leadsets.ai/docs/api/jobs) [Next
**SDKs →**](https://www.leadsets.ai/docs/sdks)

Was this page useful? [Tell us](mailto:support@leadsets.ai?subject=Docs%20feedback%3A%20%2Fdocs%2Fapi%2Fusage)

```bash
curl https://api.leadsets.ai/v1/usage \
 -H "Authorization: Bearer $LEADSETS_KEY"
```

```ts
import { Leadsets } from "@leadsetsai/sdk";

const ls = new Leadsets(process.env.LEADSETS_KEY);
const usage = await ls.usage.get();
console.log(usage.search.records_5h); // [used, limit]
```

```python
import os
from leadsets import Leadsets

ls = Leadsets(os.environ["LEADSETS_KEY"])
usage = ls.usage.get()
print(usage.search.records_5h)  # [used, limit]
```

Response 200 OK

```
{
 "plan": "team",
 "enrich": {
   "records_5h": [12500, 150000], "requests_5h": [13100, 750000],
   "records_week": [84200, 750000],
   "resets_at": "2026-11-11T17:00:00Z",
   "week_resets_at": "2026-11-15T09:00:00Z"
 },
 "search": {
   "records_5h": [3000, 75000], "requests_5h": [140, 375000],
   "records_week": [21000, 375000],
   "resets_at": "2026-11-11T16:20:00Z",
   "week_resets_at": "2026-11-14T11:00:00Z"
 },
 "personal_emails_week": [1200, 75000],
 "concurrent_searches": [1, 8],
 "scrape_units": 4200,
 "scraping": true,
 "usage": {},
 "request_id": "req_51d0c2b7e9aa"
}
```

---

Leadsets by Mobylogix LLC, 10160 hwy 242, Conroe, TX, 77385, US. Facts for AI assistants: https://www.leadsets.ai/llm · Site index: https://www.leadsets.ai/llms.txt · Every page: https://www.leadsets.ai/llms-full.txt