> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.llynx.io/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.llynx.io/docs/_mcp/server.

# Read balances

GET https://api.llynx.io/v2/audio/credits

Reads your remaining prepaid credit.

Call it before sending a batch of work, to decide when to buy a pack, or to show usage to your own users. Speech-to-text and text-to-speech balances are independent and reported separately, with the seconds and characters they still cover. `billing_hold` is true when a payment problem is blocking requests on the account. Negative balances after refunds remain visible.

Reference: https://api.llynx.io/docs/api-reference/credits

## Authentication

- `Authorization` header (bearer token, required) — Your Llynx API key, sent as `Authorization: Bearer <key>`.

## Response

### 200

Current balances for both services

- `stt` (Balance, required)
- `tts` (Balance, required)
- `billing_hold` (boolean, required) — True when a payment problem is blocking requests on the account.
- `as_of` (datetime, required) — Time of this snapshot.

## Errors

### 401 Unauthorized Error

Missing or invalid API key

- `error` (ErrorError, required)

### 403 Forbidden Error

This key or account is not allowed to make the request, or the account is on a billing hold

- `error` (ErrorError, required)

### 503 Service Unavailable Error

Temporarily unavailable; a request that fails after admission is refunded

- `error` (ErrorError, required)

## Types

### Balance

- `credit_unit` (enum, required) — `stt_credit` for speech to text, `tts_credit` for text to speech.
  - Allowed values: `stt_credit`, `tts_credit`
- `allocated` (double, required) — Credits granted so far: the introductory award plus purchased packs.
- `used` (double, required) — Credits settled by completed requests.
- `reserved` (double, required) — Credits held by requests still in flight.
- `available` (double, required) — Credits you can spend now: allocated minus used and reserved.
- `transcribed_seconds` (double, required) — Audio seconds transcribed to date (speech to text).
- `generated_seconds` (double, required) — Audio seconds generated to date (text to speech).
- `input_characters` (integer, required) — Input characters synthesized to date (text to speech).
- `seconds_per_credit` (integer, optional) — Seconds one credit covers (speech to text).
- `characters_per_credit` (integer, optional) — Characters one credit covers (text to speech).
- `available_seconds` (integer, optional) — Audio seconds the available credit still covers (speech to text).
- `available_characters` (integer, optional) — Input characters the available credit still covers (text to speech).

### ErrorError

- `code` (string, required) — Stable machine-readable code.
- `message` (string, required) — Readable explanation, safe to log.
- `request_id` (string, required) — Quote this when you contact us about the request.
- `retryable` (boolean, required) — True only when an immediate retry is safe.

## Examples

**Response**

```json
{
  "stt": {
    "credit_unit": "stt_credit",
    "allocated": 6100,
    "used": 12.5,
    "reserved": 0.75,
    "available": 6086.75,
    "transcribed_seconds": 250,
    "generated_seconds": 0,
    "input_characters": 0,
    "seconds_per_credit": 20,
    "available_seconds": 121735
  },
  "tts": {
    "credit_unit": "tts_credit",
    "allocated": 5100,
    "used": 3.29,
    "reserved": 0,
    "available": 5096.71,
    "transcribed_seconds": 0,
    "generated_seconds": 41.2,
    "input_characters": 329,
    "characters_per_credit": 100,
    "available_characters": 509671
  },
  "billing_hold": false,
  "as_of": "2026-10-18T21:30:00Z"
}
```

**SDK Code**

```python Python
import os
import requests

response = requests.get(
    "https://api.llynx.io/v2/audio/credits",
    headers={"Authorization": f"Bearer {os.environ['LLYNX_API_KEY']}"},
)
response.raise_for_status()
balances = response.json()
print(balances["stt"]["available"], "STT credits,", balances["tts"]["available"], "TTS credits")
```

```javascript JavaScript
const response = await fetch("https://api.llynx.io/v2/audio/credits", {
  headers: { Authorization: `Bearer ${process.env.LLYNX_API_KEY}` },
});
if (!response.ok) throw new Error(await response.text());
const balances = await response.json();
console.log(balances.stt.available, "STT credits,", balances.tts.available, "TTS credits");
```

```go Go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.llynx.io/v2/audio/credits", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LLYNX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("%s: %s", resp.Status, body)
	}
	var balances struct {
		STT struct {
			Available float64 `json:"available"`
		} `json:"stt"`
		TTS struct {
			Available float64 `json:"available"`
		} `json:"tts"`
	}
	if err := json.Unmarshal(body, &balances); err != nil {
		log.Fatal(err)
	}
	fmt.Println(balances.STT.Available, "STT credits,", balances.TTS.Available, "TTS credits")
}
```

```java Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Balances {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.llynx.io/v2/audio/credits"))
            .header("Authorization", "Bearer " + System.getenv("LLYNX_API_KEY"))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 200) {
            throw new RuntimeException(response.statusCode() + " " + response.body());
        }
        // JSON with "stt" and "tts" balances; parse it with your JSON library.
        System.out.println(response.body());
    }
}
```

```swift Swift
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

let key = ProcessInfo.processInfo.environment["LLYNX_API_KEY"] ?? ""
var request = URLRequest(url: URL(string: "https://api.llynx.io/v2/audio/credits")!)
request.setValue("Bearer \(key)", forHTTPHeaderField: "Authorization")

let (data, response) = try await URLSession.shared.data(for: request)
let http = response as! HTTPURLResponse
guard http.statusCode == 200 else {
    fatalError("\(http.statusCode): \(String(decoding: data, as: UTF8.self))")
}
let balances = try JSONSerialization.jsonObject(with: data) as! [String: [String: Any]]
print(balances["stt"]!["available"]!, "STT credits,", balances["tts"]!["available"]!, "TTS credits")
```