Credits

Cleanlist API calls that search, read, save, estimate or poll are free. A work email costs 1 credit, a direct dial 10 and both on one row 11, and a lookup that finds nothing costs 0.

Cleanlist bills enrichment, smart agents and sync in credits shared by the whole organization. This page covers the three credit endpoints and the full cost table.

Balance

GET /credits/balance

Scope: credits:read · Cost: free

curl https://api.cleanlist.ai/api/v2/credits/balance \
  -H "Authorization: Bearer clapi_your_api_key"

{
  "organization_id": "org_2xyz...",
  "credits": 4820,
  "timestamp_ms": 1717430400000,
  "agent_instructions": "You have 4820 credits remaining."
}

credits is a plain integer: the credits available to your whole organization.

Estimates and the quote model

POST /credits/estimate

Scope: credits:read · Cost: free

Prices a paid operation. Returns a quote_id bound (with HMAC-SHA256) to the exact request shape: tool, list or cohort, scope, row count, destination and your organization. The quote lasts 5 minutes and can be used once. At execution the server recomputes the real cost and rejects the call with spend_cap_exceeded if it would exceed the quote.

When you pass a list_id (or a cohort task_id), the row count is always derived on the server; any row_count you send is ignored, so you can't under-quote a large list.

Request body

Response

{
  "quote_id": "qte_v1_1717430400_3f2c...e9",
  "expires_at": 1717430700,
  "estimated_cost": 110,
  "tool": "enrich_list",
  "row_count": 10,
  "filter_hash": "a1b2c3d4e5f6a7b8",
  "available_credits": 4820,
  "sufficient": true
}

curl -X POST https://api.cleanlist.ai/api/v2/credits/estimate \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tool": "enrich_list", "list_id": "LIST_ID", "scope": "full"}'

Quote lifecycle

1. Estimate: mint a quote_id for the request shape.
2. Execute: pass the quote_id to the paid endpoint. The server checks the signature and recomputes the cost.
3. Single use: a quote can't be redeemed twice (quote_already_redeemed: 409 on smart agents and sync, 400 on enrichment).
4. Expiry: after 5 minutes the quote is rejected (quote_expired); estimate again.
5. Shape change: a quote for a different list, scope, destination or mapping is rejected (quote_mismatch). If the cost grew past the quote, you get spend_cap_exceeded. A row count may drift by up to 10% before the quote is rejected.
6. Can't confirm: if the server can't confirm the quote is unused, it returns 503 quote_verification_unavailable (retryable).

Insufficient credits

Paid operations check your balance before they start. If you can't cover the cost, you get HTTP 400 with code insufficient_credits:

{
  "error": {
    "code": "insufficient_credits",
    "problem": "This enrich_person call requires 11 credits; organization has 4.",
    "fix": "Top up at app.cleanlist.ai/billing, or reduce the scope of the call.",
    "retryable": false,
    "docs_url": "https://docs.cleanlist.ai/errors/insufficient-credits",
    "request_id": "req_...",
    "estimated_cost_credits": 11,
    "available_credits": 4,
    "shortfall_credits": 7
  }
}

The estimated_cost_credits, available_credits and shortfall_credits fields tell you exactly how much to add.

Usage reports

GET /usage

Scope: admin:api_keys · Cost: free

Aggregates your organization's API request log over a window.

curl "https://api.cleanlist.ai/api/v2/usage?days=30&group_by=tool" \
  -H "Authorization: Bearer clapi_your_api_key"

{
  "days": 30,
  "group_by": "tool",
  "total_calls": 1820,
  "total_credits_spent": 312,
  "total_errors": 12,
  "rows": [
    { "group": "/enrichment/bulk", "calls": 240, "credits_spent": 264, "errors": 3 },
    { "group": "/people/find", "calls": 980, "credits_spent": 0, "errors": 1 }
  ]
}

With group_by=tool, rows are bucketed by the endpoint template (the path without the /api/v2 prefix, for example /enrichment/person or /lead-lists/{list_id}/leads). credits_spent and total_credits_spent are whole numbers: each request's cost is rounded up before it's logged. The figure is the cost reserved at dispatch, not the settled charge after pay-for-results refunds. Free endpoints (search, saving leads) report 0.

Credit cost table

Costs are computed per request and the total is rounded up to a whole credit. Reads are always free. Use the tool name with POST /credits/estimate.

Learn more

• Enrichment endpoints
• Enrichment types & pricing
• Smart agents
• CRM & Sequencer Sync
• Authentication & scopes
• Errors & rate limits