Billing API
Read your workspace's plan, credits, usage report, credit history and billing alerts. Read only: nothing here changes the plan, buys credits or shows a card.
GET /v1/billing → GET /v1/billing/usage → GET /v1/billing/credit-transactionsScope billing_usage:read4 endpointsShow
Who can read billing
Keys need billing_usage:read. Only owners and admins can give a key this permission, it is never part of a default or a preset, and reseller keys never hold it. Every read runs as the member who created the key: when they stop being an owner or admin, or leave the workspace, the key is refused.
Invoices, cards and payment methods, buying credits, changing the plan and the alerts' settings stay in NuTalk (Settings → Billing). A workspace whose billing its reseller manages has no billing to read here.
/v1/billingGet the plan and credits
The workspace's plan, the currency it pays in (currency null while it pays in none yet), the current credit period, and its credits: the balance, what the period used, the plan's monthly allowance, what was bought and used of it, and whether the workspace is suspended. Never a card or a payment method.
billing_usage:readWorkspace keys only · acts as the key's creatorReads run as the member who created the key: they must read Billing in NuTalk now (an owner or admin). A workspace whose billing its reseller manages, a key whose creator has left or was demoted, and a reseller key are refused.
Errors
403forbiddenThe key's creator isn't an owner or admin now, has left the workspace, or the workspace's billing is its reseller's (details.reason BILLING_MANAGED_BY_RESELLER), or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/billing \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"plan": {
"code": "growth",
"name": "Growth",
"kind": "subscription",
"monthly_credits": 2000
},
"currency": "mxn",
"currency_locked": true,
"period": {
"start": "2026-10-12T00:00:00+00:00",
"end": "2026-11-12T00:00:00+00:00"
},
"credits": {
"balance": 1240.5,
"used_this_period": 759.5,
"monthly_allowance": 2000,
"plan_credits_used": 759.5,
"bought": 0,
"bought_used": 0,
"overuse": 0
},
"suspended": false,
"suspension_reason": null
}
}/v1/billing/usageGet the usage report
The credits used each day of a period (up to 90 days), by agent, channel and campaign, with their names, in the workspace's time zone: the report the dashboard's Usage sheet shows.
billing_usage:readWorkspace keys only · acts as the key's creatorReads run as the member who created the key: they must read Billing in NuTalk now (an owner or admin). A workspace whose billing its reseller manages, a key whose creator has left or was demoted, and a reseller key are refused.
Query parameters
periodlast30 | thisMonth | lastMonth | last3Months | customThe period; custom takes from and to. Default: last30.
fromstringWith custom: the first day (YYYY-MM-DD).
tostringWith custom: the last day (YYYY-MM-DD, today at the latest).
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).400validation_errorA custom period longer than 90 days or ending after today (details.reason USAGE_PERIOD_INVALID).403forbiddenThe key's creator isn't an owner or admin now, has left the workspace, or the workspace's billing is its reseller's (details.reason BILLING_MANAGED_BY_RESELLER), or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/billing/usage?period=thisMonth" \ -H "Authorization: Bearer $NUTALK_API_KEY"
type, bucket, kind) for an agent, a channel and a campaign (null when it has none), with its units (minutes, messages…).{
"success": true,
"data": {
"period": "thisMonth",
"from": "2026-10-01",
"to": "2026-10-27",
"today": "2026-10-27",
"days": [
"2026-10-26",
"2026-10-27"
],
"lines": [
{
"day": "2026-10-27",
"type": "usage",
"bucket": "calls",
"kind": "voice_minute",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"campaign_id": null,
"credits": 42,
"units": 21
}
],
"agents": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sofía"
}
],
"channels": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Support line",
"type": "voice"
}
],
"campaigns": [],
"events": []
}
}/v1/billing/credit-transactionsList the credit history
The workspace's credit history, newest first: each grant, purchase, use and refund (type, a signed amount), the balance after it, and for a use the call, contact, test run or campaign it was for and its billed minutes. Never its payment's Stripe ids.
billing_usage:readWorkspace keys only · acts as the key's creatorReads run as the member who created the key: they must read Billing in NuTalk now (an owner or admin). A workspace whose billing its reseller manages, a key whose creator has left or was demoted, and a reseller key are refused.
Query parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
sincedatetimeOnly lines from this moment on.
untildatetimeOnly lines before this moment.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).403forbiddenThe key's creator isn't an owner or admin now, has left the workspace, or the workspace's billing is its reseller's (details.reason BILLING_MANAGED_BY_RESELLER), or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/billing/credit-transactions?limit=50" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
"type": "usage",
"amount": -2,
"balance_after": 1240.5,
"reference_type": "call",
"reference_id": "1ba11348-e440-44de-a5cd-5fe62f4d9df6",
"description": "Voice call",
"call_id": "1ba11348-e440-44de-a5cd-5fe62f4d9df6",
"contact_id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"test_run_id": null,
"campaign_id": null,
"billed_minutes": 1,
"created_at": "2026-10-27T18:20:05.117+00:00"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}
}/v1/billing/alertsGet the billing alerts
The billing alerts: low credits (and below how many), the monthly usage limit (its credits, the share at which it warns, and what it does when reached), and the other addresses the alerts are emailed to (pending_emails haven't confirmed yet). They are changed in NuTalk (Settings → Billing).
billing_usage:readWorkspace keys only · acts as the key's creatorReads run as the member who created the key: they must read Billing in NuTalk now (an owner or admin). A workspace whose billing its reseller manages, a key whose creator has left or was demoted, and a reseller key are refused.
Errors
403forbiddenThe key's creator isn't an owner or admin now, has left the workspace, or the workspace's billing is its reseller's (details.reason BILLING_MANAGED_BY_RESELLER), or the key is a reseller key.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/billing/alerts \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"low_credits": {
"enabled": true,
"threshold": 200,
"default": true
},
"usage_limit": {
"enabled": false,
"credits": null,
"alert_percent": 80,
"action": "notify"
},
"extra_emails": [
"finance@example.com"
],
"pending_emails": []
}
}