Credits

Cleanlist bills enrichment and sync work in credits. 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/v1/public/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 & the quote model

POST /credits/estimate

Scope: credits:read · Cost: free

Pre-flight a paid operation. Returns a quote_id bound (via HMAC-SHA256) to the exact request shape — tool, list/filters, scope, row count, and your org. The quote has a 5-minute TTL. Paid bulk endpoints accept (and in some cases require) this quote_id; at execution time the server recomputes the real cost and rejects with spend_cap_exceeded if it would exceed the quote.

When you pass a list_id, the row count is always derived from the list — your row_count 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/v1/public/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 quote_id to the paid endpoint. The server verifies the signature and recomputes cost.
3. Single use → a quote can't be redeemed twice (quote_already_redeemed).
4. Expiry → after ~5 minutes the quote is rejected (quote_expired); just re-estimate.
5. Drift → if the actual cost exceeds the quote, you get spend_cap_exceeded — re-estimate against the current shape.

Insufficient credits

Paid operations check your balance up front. If you can't cover the cost, you get HTTP 400 with code insufficient_credits (not 402):

{
  "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

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

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

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

Credit cost table

Costs are computed per request and rounded up (ceiling). Reads are always free.

Learn more

• Enrichment endpoints
• Enrichment types & pricing
• Authentication & scopes
• Errors & rate limits