Credit Budgets
Create and manage credit budgets with spend caps, periods, and low-balance alert thresholds.
https://api.leadmagic.io/v1/batch/budgetsTry 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.
- Pricing
- Rate Limits
| Metric | Value |
|---|---|
| Cost | FREE: managing budgets does not consume credits |
Create Budget
POST /v1/batch/budgets: create a new credit budget.
The scope type for this budget (e.g. user, client). Defines how scope_value is interpreted.
The identifier within the scope (e.g. a user ID, client ID) whose credit spend this budget caps.
Maximum credits that can be consumed within the period. Must be a positive number.
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 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.
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 scopemaxCredits: the capremainingCredits: credits remaining in the current periodisExceeded:trueif 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.
New maximum credits. Must be positive.
New reset period. Must be a non-empty string.
New alert threshold (0–1, exclusive).
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 for low-balance alerts
Set alert_threshold_pct for low-balance alerts
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.
Use budget_user_id with preview-cost
Use budget_user_id with preview-cost
Pass budget_user_id (matching a budget's scope_value) to Preview Batch Cost to check willExceedBudget before submitting a batch.
Period resets budget counters
Period resets budget counters
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.
Set up budgets before submitting large jobs
Set up budgets before submitting large jobs
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.