Billing

Get plan and remaining usage

GET/api/v1/billing/balance

Returns the selected organization's plan, its overage cap, its Stripe subscription state (null on the free hobby plan), and the remaining seconds for each metered resource. Usage is metered in seconds, not money: a plan grants a number of seconds per period and sessions debit them. On a paid plan secondsRemaining may be negative, which is overage billed at the end of the period up to overageCapUsd. Visible to every member of the organization.

Header parameters

X-Organization-Idstring

Selects which of the caller's organizations the request acts on. When omitted, the caller's default organization is used.

Returns

accountTypestringrequired

The organization's plan.

overageCapUsdnumberrequired

Dollars of overage allowed past the plan's included seconds in one period, at $0.15 per minute. 0 means the organization hard-stops when it runs out.

subscriptionobjectrequirednullable

The Stripe subscription backing a paid plan, or null on the free hobby plan.

Show child attributes

statusstringrequired

Stripe subscription status. active, trialing, and past_due all keep the plan's entitlements; the plan ends only when the subscription is deleted.

currentPeriodEndstring · date-timerequired

When the current billing period ends, and the included seconds are granted again.

cancelAtPeriodEndbooleanrequired

True when the subscription is set to end at currentPeriodEnd rather than renew.

resourcesarrayrequired

Remaining usage per metered resource. Today only mobile is metered; more resources are added as array entries, so read the entry whose resource you want rather than the first one.

Show child attributes

resourcestringrequired

A metered resource. Only "mobile" exists today; more are added over time, so treat an unrecognised value as a resource you do not handle rather than an error.

secondsRemainingintegerrequired

Seconds left in the current period. Negative on a paid plan means overage already used, billed on the next invoice up to overageCapUsd.

periodStartstring · date-timerequirednullable

Start of the period this balance belongs to, or null when the organization has never been granted any.

periodEndstring · date-timerequirednullable

End of the period this balance belongs to, or null when the organization has never been granted any.

Request

curl https://app.mobilenext.ai/api/v1/billing/balance \
  -X GET \
  -H 'Authorization: Bearer mob_...'

Response

Current plan, subscription, and usage balances

{
  "accountType": "starter",
  "overageCapUsd": 25,
  "subscription": {
    "status": "active",
    "currentPeriodEnd": "2026-01-01T00:00:00Z",
    "cancelAtPeriodEnd": true
  },
  "resources": [
    {
      "resource": "mobile",
      "secondsRemaining": 11400,
      "periodStart": "2026-01-01T00:00:00Z",
      "periodEnd": "2026-01-01T00:00:00Z"
    }
  ]
}