---
title: "Read your Speak AI plan, credits and billing status"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Read your Speak AI plan, credits and billing status


import EndpointIndex from "@/components/api/EndpointIndex.astro";

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](/api/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.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/subscription/billing-status`](#get-subscription-billing-status) | Get billing status |

<h2 id="get-subscription-billing-status">Get billing status</h2>

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.

<div slot="code">

<CodePanel label="Example request">

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

</CodePanel>

<ResponsePanel id="get-subscription-billing-status" statuses={[{"code":"200","description":"OK"},{"code":"401","description":"Unauthorized"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |

<details>
<summary>`data` -- 9 more fields</summary>

| 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. |

<details>
<summary>`options` -- 7 more fields</summary>

| 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`. |

</details>

</details>

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

```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"
  }
}
```

</div>

<div slot="status-401">

**`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`.

```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."
  ]
}
```

</div>

</ResponsePanel>

</div>

## Related pages

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

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-billing).

Source: https://docs.speakai.co/api/billing/index.mdx