Resource

Billing

Read endpoints for FUEL — current balance, the transaction ledger, and aggregated consumption by service. Read-only; topping up still happens through the dashboard.

Org-level always

FUEL is per-organization, not per-client. Both agency and client keys see the same balance, the same transaction history, the same usage roll-ups. Tenancy isolation doesn't apply here because there's nothing per-client to isolate.

Current balance#

Current FUEL balance + subscription state

GET/v1/billing/balance

Useful for n8n flows that want to skip expensive AI-flagged operations when the agency is low on credits.

Response

{
  "balance": 184250,
  "subscription_status": "active",
  "package_slug": "scale",
  "auto_reload": {
    "enabled": true,
    "threshold": 10000,
    "target": 50000
  },
  "spending_cap": {
    "monthly_limit": 200000,
    "current_month_spend": 12500
  },
  "account_frozen": false,
  "frozen_reason": null,
  "last_reload_at": "2026-04-26T14:02:00.000Z",
  "updated_at": "2026-04-28T01:18:50.000Z"
}

Response fields:

balanceinteger

Whole FUEL units. 1 unit = $0.01 of platform cost.

subscription_statusstring

active, past_due, cancelled, inactive.

package_slugstring | null

Current package the agency is subscribed to.

auto_reloadobject

enabled, threshold (trigger), target (top-up to).

spending_capobject | null

Monthly auto-reload cap. Null when no cap is set.

account_frozenboolean

When true, FUEL-metered services 402 immediately.

frozen_reasonstring | null

Human-readable cause when account_frozen=true.

Usage by service#

Aggregated FUEL consumption by service_type

GET/v1/billing/usage

Defaults to the last 30 days. Max range: 365 days.

Query parameters

fromiso date

Start of window (default: 30 days ago).

toiso date

End of window (default: now).

Response

{
  "window": { "from": "2026-03-29T00:00:00.000Z", "to": "2026-04-28T00:00:00.000Z" },
  "total_credits_consumed": 32140,
  "total_transactions": 1872,
  "by_service": [
    { "service_type": "elevenlabs_voice_minutes", "credits_consumed": 18420, "transaction_count": 412 },
    { "service_type": "telnyx_sms_outbound",     "credits_consumed":  6204, "transaction_count": 1204 },
    { "service_type": "ai_lead_summary",          "credits_consumed":  1480, "transaction_count":  148 }
  ]
}

Transaction ledger#

Paginated FUEL transactions

GET/v1/billing/transactions

All ledger movements: consumption, auto_reload, manual_topup, subscription_credit, expirations, adjustments. Filter by type or service_type.

Query parameters

limitintegerdefault: 50

1–200

page_tokenstring

typestring

Filter — consumption, auto_reload, manual_topup, subscription_credit, expiration, forfeiture, adjustment, chargeback_reversal, package_switch.

service_typestring

Filter to one service (e.g. elevenlabs_voice_minutes).

fromiso date

Default: 30 days ago.

toiso date

Default: now.

Response

{
  "data": [
    {
      "id": "tx_EXAMPLE_aaaa",
      "type": "consumption",
      "amount": -42,
      "balance_after": 184208,
      "service_type": "elevenlabs_voice_minutes",
      "description": "Voice call cl_call_xyz · 2.1 min",
      "created_at": "2026-04-28T01:14:22.000Z"
    },
    {
      "id": "tx_EXAMPLE_bbbb",
      "type": "auto_reload",
      "amount": 50000,
      "balance_after": 184250,
      "service_type": null,
      "description": "Auto-reload — Scale package threshold hit",
      "created_at": "2026-04-26T14:02:00.000Z"
    }
  ],
  "next_page_token": null,
  "total": 2
}

Webhooks for billing#

credits.low_balance — balance crossed the configured threshold.
credits.auto_reload — auto-reload fired.
credits.exhausted — balance hit zero, FUEL-metered services 402'd.