Clay logo

LeadMagic has made more than one billion API calls with Clay and won The Unstoppable Wheel award.

Recap
LeadMagicDocs

Credit Budgets

Create and manage credit budgets with spend caps, periods, and low-balance alert thresholds.

POSThttps://api.leadmagic.io/v1/batch/budgets
Try this endpointOpen the API playground

Endpoint Details

Create and manage credit budgets that cap spend on batch submissions. Two scopes are enforced: user (the team member who submits) and client (the batch's client_id). Once a budget is used up, new batch submissions for that scope are refused with 402 budget_exceeded.

Budgets don't apply to bulk jobs. A monthly budget counts the current calendar month; any other period counts all usage to date.

MetricValue
CostFREE: managing budgets does not consume credits

Create Budget

POST /v1/batch/budgets: create a new credit budget.

scope
string
required

The scope type for this budget (e.g. user, client). Defines how scope_value is interpreted.

scope_value
string
required

The identifier within the scope (e.g. a user ID, client ID) whose credit spend this budget caps.

max_credits
number
required

Maximum credits that can be consumed within the period. Must be a positive number.

period
string

Reset period for the budget counter (e.g. daily, weekly, monthly). When the period resets, the consumed counter returns to zero. Omit for a non-resetting (lifetime) budget.

alert_threshold_pct
number

Alert threshold as a fraction between 0 and 1 (exclusive). When consumed credits reach this fraction of max_credits, an alert email is sent to alert_email. E.g. 0.8 alerts at 80% consumption.

alert_email
string

Email address to receive low-balance alerts when alert_threshold_pct is reached.

Returns 201 with the created budget object.


List Budgets

GET /v1/batch/budgets: list all budgets for the authenticated account.

Returns 200 with an array of budget objects.


Get Budget Status

GET /v1/batch/budgets/status: consumption status for all budgets.

Returns 200 with an array of budget status objects, each including:

  • scope, scope_value: the budget scope
  • maxCredits: the cap
  • remainingCredits: credits remaining in the current period
  • isExceeded: true if the budget has been reached

Use GET /v1/batch/budgets/status with Preview Batch Cost: pass budget_user_id matching a budget's scope_value to check whether a batch will exceed the budget before submitting.


Update Budget

PATCH /v1/batch/budgets/:id: update max_credits, period, alert_threshold_pct, and/or alert_email. At least one field is required.

max_credits
number

New maximum credits. Must be positive.

period
string

New reset period. Must be a non-empty string.

alert_threshold_pct
number

New alert threshold (0–1, exclusive).

alert_email
string

New alert email. Pass an empty string to clear.

Returns 200 with the updated budget, or 404 if not found.


Delete Budget

DELETE /v1/batch/budgets/:id: hard-delete a budget.

Returns 200 with a confirmation object.


Status Codes

200

OK: budget retrieved, updated, or deleted

201

Created: budget created

400

Bad Request: missing required field, invalid max_credits, or alert_threshold_pct out of range

401

Unauthorized: invalid or missing API key

404

Not Found: budget ID does not exist or belongs to another account

429

Rate Limit: too many requests; retry after backoff


Best Practices

Set alert_threshold_pct to 0.8 (80%) and provide alert_email to get notified before a budget is exhausted. This gives you time to top up credits or reduce batch sizes before the budget cap kicks in.

Pass budget_user_id (matching a budget's scope_value) to Preview Batch Cost to check willExceedBudget before submitting a batch.

When period resets (e.g. at the start of a new month for monthly), the consumed-credits counter returns to zero. Choose a period that matches your billing cycle.

Create budgets and suppression lists first, then submit via Submit Batch. A submission is refused with 402 budget_exceeded once the budget is used up.