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/usageMCP: 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.

Errors

Status	type	Meaning
`401`	`unauthorized`	Missing, invalid, expired or revoked key. See Authentication.

Previous
← GET /jobs/{id}Next
SDKs →

Was this page useful? Tell us

cURLTypeScriptPython

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

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]

import os
from leadsets import Leadsets

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

Response200 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"
}