Read your Speak AI plan, credits and billing status

Read the plan, credits left, renewal and trial dates, pending payments and purchase options of your Speak AI account, so an agent knows when a retry can work.

The Speak AI API exposes 1 billing endpoint under the base URL https://api.speakai.co/v1. Every request needs your API key in the x-speakai-key header, as described in Authentication. No access token is needed.

Read the plan, credits and billing options of your account.

What can you do with the billing endpoints?

Speak AI groups these 1 endpoint under the billing resource. Each entry below links to the full reference for that endpoint further down this page.

Get billing status

GET/subscription/billing-status

Read the plan and credits of the account the API key belongs to: the plan, the credits left, when the plan renews, when the trial ends, whether a payment is pending, a link to manage billing, and the options the account can buy.

Call it after a request is refused for credits and before you retry. Retry only when it shows enough credits.

Options come in the order Speak AI suggests. A key created by connecting an AI assistant gets no options and no checkoutUrl or manageUrl. Any other key, such as one used by a script or automation, gets a top-up with auto-reload first.

Example request

curl -X GET 'https://api.speakai.co/v1/subscription/billing-status' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000'

Response

200 OK

Response body, application/json.

Field	Type
`status`	string
`data`	object

data – 9 more fields

Field	Type	Description
`plan`	string	The plan the account is on. `custom` covers every other paid plan. One of: `free_trial`, `pay_as_you_go`, `pro`, `custom` .
`creditsRemaining`	number	Credits the account has left to spend.
`renewsAt`	string (date)	The day a paid plan renews and adds its next credits. Present only on `pro` and `custom` plans.
`trialEndsAt`	string (date)	The day the free trial ends or ended. Present only on `free_trial`.
`pendingPayment`	boolean	Whether a subscription payment is pending. When true, `options` is empty and the person needs to update their payment method.
`canManageBilling`	boolean	Whether the person calling can pay or change the plan. When false, there is no `checkoutUrl`, so ask them to contact an account admin.
`manageUrl`	string	Link to the payment page in the Speak AI app, `https://app.speakai.co/profile/payment`, where the person can change or cancel the plan.
`options`	object[]	What the account can buy. A top-up carries its price and credits; the Pro option carries only its link. Empty for invoiced accounts and while a payment is pending. Only a top-up is offered on an active paid plan or a subscription bought in the mobile app.
`checkoutUrl`	string	The link of the recommended option, or the payment page while a payment is pending. Absent when the person cannot manage billing.

options – 7 more fields

Field	Type	Description
`id`	string	Which option this is: `pro` for the Pro plan, `top_up` for prepaid credit. One of: `pro`, `top_up` .
`recommended`	boolean	Whether this is the option Speak AI suggests first. Exactly one option is recommended.
`amount`	number	Top-up price in `currency`: $20 or the shortfall for the blocked action, whichever is larger. Present only on a top-up; the Pro option carries no price.
`currency`	string	Currency code, `USD`. Present only on a top-up.
`credits`	number	Credits the top-up adds. Present only on a top-up.
`autoReload`	boolean	Present on a top-up suggested for a script or automation, which should turn on auto-reload so it does not stop again.
`url`	string	Link that opens the matching payment dialog in the Speak AI app: `/home?keep-going=pro` or `/home?keep-going=top-up` on `https://app.speakai.co`.

Example response (Trial account with no credits left, called with an API key), application/json.

{
  "status": "success",
  "data": {
    "plan": "free_trial",
    "creditsRemaining": 0,
    "trialEndsAt": "2026-11-14",
    "pendingPayment": false,
    "canManageBilling": true,
    "manageUrl": "https://app.speakai.co/profile/payment",
    "options": [
      {
        "id": "top_up",
        "recommended": true,
        "amount": 20,
        "currency": "USD",
        "credits": 20,
        "autoReload": true,
        "url": "https://app.speakai.co/home?keep-going=top-up"
      },
      {
        "id": "pro",
        "recommended": false,
        "url": "https://app.speakai.co/home?keep-going=pro"
      }
    ],
    "checkoutUrl": "https://app.speakai.co/home?keep-going=top-up"
  }
}

401 Unauthorized

Response body, application/json.

Field	Type
`status`	string
`requestId`	string
`code`	integer
`message`	string
`hints`	string[]

Example response (Invalid API key), application/json.

{
  "status": "failed",
  "requestId": "ca665625-645e-438a-867d-366a6e3f133a",
  "code": 401,
  "message": "The authorization api key provided for the request is invalid.",
  "hints": [
    "The authorization api key provided for the request is invalid."
  ]
}

API reference for the base URL, authentication, and the error format.
Authenticate with the Speak AI API using an API key
Upload audio and video to Speak AI and read insights
Create and update live transcription sessions
Analyze text notes with the Speak AI text endpoints

Get an API key on the Speak AI developer page.

Read your Speak AI plan, credits and billing status

What can you do with the billing endpoints?

Get billing status

Related pages