LeadMagic — API auth, credits & plans
Rules
- Never echo or log
LEADMAGIC_API_KEY. Read from env only; rotate immediately if a key was pasted into chat or committed.
- REST auth header is
X-API-Key, not Authorization: Bearer.
- Prefer hosted MCP (
https://mcp.leadmagic.io/mcp) for agent workflows — OAuth, no key in shell history.
- Preflight every run:
GET /v1/credits (free). Preview anything ≥ 500 credits: POST /v1/batch/preview-cost (free).
Base URL & key
curl -sS "https://api.leadmagic.io/v1/credits" -H "X-API-Key: $LEADMAGIC_API_KEY"
Plans (what a run can afford)
Basic $49.99/mo · 2,000 credits (no rollover, 1 seat) → Essential $99 · 5,000 → Growth $249 · 20,000 → Professional $499 · 50,000 → Ultimate $849 · 100,000 (rollover on Essential+). Annual = 12× credits up front at ~2 months free. Professional/Ultimate include credit-free Search API throughput (5/10 req/s) — v3 searches cost 0 credits there and 1 credit/row elsewhere. Full ladder + budgeting: leadmagic skill → references/plans-and-limits.md.
Status codes
| Code |
Meaning |
What to do |
| 400 |
Validation |
Error body names the field and the fix (detail, action) |
| 401 |
Missing/invalid key |
Check header name (X-API-Key) and env var; key may be revoked |
| 402 |
Out of credits |
Stop the run; report done/remaining; GET /v1/credits; resume after top-up. Never retry-loop |
| 403 |
Plan/entitlement gate |
Feature not on this plan — say which plan unlocks it |
| 429 |
Rate limited |
Honor Retry-After, exponential backoff + jitter. Sustained hammering escalates temporary blocks |
| 5xx |
Transient |
One retry with backoff, then surface with trace.request_id |
Errors are RFC 9457 Problem Details — action is the machine-suggested fix; trace.request_id is what support needs.
Credit accounting facts
- Not-found results are free on the major finders (email, personal email, mobile, profile→email, company, funding).
- Email validation bills only conclusive outcomes (valid/invalid). Malformed, no-MX, disposable, and blocklisted addresses come back
invalid and bill; unknown (inconclusive SMTP, unverifiable catch-all, timeouts) is free.
- Bulk jobs bill per successful row at single-request rates; failed rows free.
- Track spend with free
GET /v1/analytics/usage, /credits, /day/{date} (see analytics-observability).
1---2name: api-auth-credits3description: LeadMagic API authentication, API keys, credit balance, plans, and rate limits. Use when setting LEADMAGIC_API_KEY, calling GET /v1/credits, budgeting a run against a plan's credits, previewing bulk cost, or debugging 401, 402, 403, or 429 responses.4license: MIT5---67# LeadMagic — API auth, credits & plans89## Rules10111. Never echo or log `LEADMAGIC_API_KEY`. Read from env only; rotate immediately if a key was pasted into chat or committed.122. REST auth header is **`X-API-Key`**, not `Authorization: Bearer`.133. Prefer hosted MCP (`https://mcp.leadmagic.io/mcp`) for agent workflows — OAuth, no key in shell history.144. Preflight every run: `GET /v1/credits` (free). Preview anything ≥ 500 credits: `POST /v1/batch/preview-cost` (free).1516## Base URL & key1718- **Base:** `https://api.leadmagic.io`19- **Key:** [app.leadmagic.io](https://app.leadmagic.io?utm_source=github&utm_medium=skill&utm_campaign=leadmagic-skills) → Settings → API2021```bash22curl -sS "https://api.leadmagic.io/v1/credits" -H "X-API-Key: $LEADMAGIC_API_KEY"23```2425## Plans (what a run can afford)2627Basic $49.99/mo · 2,000 credits (no rollover, 1 seat) → Essential $99 · 5,000 → Growth $249 · 20,000 → Professional $499 · 50,000 → Ultimate $849 · 100,000 (rollover on Essential+). Annual = 12× credits up front at ~2 months free. **Professional/Ultimate include credit-free Search API throughput (5/10 req/s)** — v3 searches cost 0 credits there and 1 credit/row elsewhere. Full ladder + budgeting: `leadmagic` skill → `references/plans-and-limits.md`.2829## Status codes3031| Code | Meaning | What to do |32|---|---|---|33| 400 | Validation | Error body names the field and the fix (`detail`, `action`) |34| 401 | Missing/invalid key | Check header name (`X-API-Key`) and env var; key may be revoked |35| 402 | Out of credits | Stop the run; report done/remaining; `GET /v1/credits`; resume after top-up. Never retry-loop |36| 403 | Plan/entitlement gate | Feature not on this plan — say which plan unlocks it |37| 429 | Rate limited | Honor `Retry-After`, exponential backoff + jitter. Sustained hammering escalates temporary blocks |38| 5xx | Transient | One retry with backoff, then surface with `trace.request_id` |3940Errors are RFC 9457 Problem Details — `action` is the machine-suggested fix; `trace.request_id` is what support needs.4142## Credit accounting facts4344- Not-found results are **free** on the major finders (email, personal email, mobile, profile→email, company, funding).45- Email validation bills only conclusive outcomes (valid/invalid). Malformed, no-MX, disposable, and blocklisted addresses come back `invalid` and bill; `unknown` (inconclusive SMTP, unverifiable catch-all, timeouts) is free.46- Bulk jobs bill per **successful** row at single-request rates; failed rows free.47- Track spend with free `GET /v1/analytics/usage`, `/credits`, `/day/{date}` (see `analytics-observability`).
LeadMagic