Budgets
List the budgets
Use it to see every budget the key can manage with what is spent this month. Newest first. Read-only and idempotent.
Required scope: budgets:read.
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List the budgets › Responses
objecthasMorenextCursorCreate a monthly budget
Use it to cap what agents can spend per month, in US dollars, for the whole organization, one subaccount, one agent or one contact. A contact budget keeps a stranger from using up the budget of everyone. At the alert percent (80 by default) the budget.threshold_reached event fires once; at the limit, with enforcement stop (the default), the agent stops and POST /v2/cases/{id}/messages answers 402 budget_exceeded until the month resets or you raise the limit. With enforcement notify the agent never stops and only the events fire. The month is counted in the time zone of the organization. Several budgets can apply to the same turn and the strictest one stops it. Creates one budget per scope and subject: a second one answers 409. Not idempotent. Do not use it to change an existing budget: use PATCH /v2/budgets/{id}.
Required scope: budgets:write.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Create a monthly budget › Request Body
scopemonthlyLimitConversationsMonthly limit in conversations. A conversation is a window per case of up to 10 agent turns or 24 hours, whichever comes first.
subjectIdRequired for subaccount (sub_), agent (agt_) and contact (ctc_). Not allowed for organization. A subaccount budget needs the platform key without Lelemon-Subaccount; the key of the subaccount cannot see or raise it.
alertPercentenforcementCreate a monthly budget › Responses
objectidscopeWhat the budget covers: the whole organization, one subaccount, one agent or one contact.
subjectIdThe sub_, agt_ or ctc_ id the budget covers. null for the organization.
monthlyLimitConversationsMonthly limit in conversations.
alertPercentPercent of the limit that fires budget.threshold_reached.
enforcementstop: at the limit the agent stops and the API answers 402 budget_exceeded. notify: the agent keeps working and only the events fire.
usedConversationsConversations used this month.
stateok: under the alert percent. alert: past it. limit_reached: the used conversations reached the limit.
createdAtupdatedAtGet a budget
Use it to check how much of a budget is spent this month and its state. Read-only and idempotent.
Required scope: budgets:read.
path Parameters
id^bgt_[0-9A-Za-z]{22}… · requiredThe id of the budget (bgt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Get a budget › Responses
objectidscopeWhat the budget covers: the whole organization, one subaccount, one agent or one contact.
subjectIdThe sub_, agt_ or ctc_ id the budget covers. null for the organization.
monthlyLimitConversationsMonthly limit in conversations.
alertPercentPercent of the limit that fires budget.threshold_reached.
enforcementstop: at the limit the agent stops and the API answers 402 budget_exceeded. notify: the agent keeps working and only the events fire.
usedConversationsConversations used this month.
stateok: under the alert percent. alert: past it. limit_reached: the used conversations reached the limit.
createdAtupdatedAtDelete a budget
Use it to remove a budget you no longer want: the agents it was stopping answer again at once and its alerts stop. The spending counted so far is deleted with it; the usage report (GET /v2/usage) is not affected. To create another budget for the same scope and subject afterwards, use POST /v2/budgets. A key of a subaccount only reaches the budgets of its own organization. Idempotent in effect: deleting it again answers 404.
Required scope: budgets:write.
path Parameters
id^bgt_[0-9A-Za-z]{22}… · requiredThe id of the budget (bgt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Delete a budget › Responses
Deleted.
Change a budget
Use it to raise or lower the limit, change the alert percent or switch between stop and notify. Raising the limit above what is spent makes a stopped agent answer again at once and re-arms the alert. The scope and the subject cannot change: create another budget instead. A key of a subaccount only reaches the budgets of its own organization; the budget that its platform set for it is not visible to it and cannot be raised from there. Idempotent: the same body leaves the same budget.
Required scope: budgets:write.
path Parameters
id^bgt_[0-9A-Za-z]{22}… · requiredThe id of the budget (bgt_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Change a budget › Request Body optional
monthlyLimitConversationsNew monthly limit in conversations. Raising it makes a stopped agent answer again at once and re-arms the alert.
alertPercentenforcementChange a budget › Responses
objectidscopeWhat the budget covers: the whole organization, one subaccount, one agent or one contact.
subjectIdThe sub_, agt_ or ctc_ id the budget covers. null for the organization.
monthlyLimitConversationsMonthly limit in conversations.
alertPercentPercent of the limit that fires budget.threshold_reached.
enforcementstop: at the limit the agent stops and the API answers 402 budget_exceeded. notify: the agent keeps working and only the events fire.
usedConversationsConversations used this month.
stateok: under the alert percent. alert: past it. limit_reached: the used conversations reached the limit.
createdAtupdatedAt