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

# GET /credits/transactions

> Your credit statement — every charge, top-up, refund and adjustment, with the balance after each

## Endpoint

```
GET https://lyrcs.ai/api/v1/credits/transactions
```

Returns your organisation's credit history, oldest entry first. Each entry shows what changed your balance, by how much, which job it was for, and the balance it left behind. Use it to reconcile credits against your own records, or to produce a statement for any period.

For just the current balance, [`GET /usage`](https://docs.lyrcs.ai/api-reference/usage) is simpler.

## Query parameters

| Parameter | Description |
| - | - |
| `since` | ISO 8601 timestamp. Only entries at or after this instant (inclusive). |
| `until` | ISO 8601 timestamp. Only entries **before** this instant (exclusive). |
| `credit_type` | One of `transcription`, `alignment`, `video-basic`, `video-pro`. Only entries for that credit type. |
| `limit` | Page size, 1–100. Default `50`. |
| `cursor` | The `next_cursor` from the previous page. Omit it to start from the beginning. |

`since` is inclusive and `until` exclusive, so consecutive periods (`since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z`, then `since=2026-10-01T00:00:00Z&until=2026-11-01T00:00:00Z`) never drop or double-count an entry on the boundary.

## Response

```json theme={null}
{
  "transactions": [
    {
      "id": "911ed3b3-1604-4345-a53c-6c3be2182a1e",
      "created_at": "2026-09-02T12:42:44.813Z",
      "type": "top_up",
      "credit_type": "alignment",
      "amount": 25,
      "balance_after": 25,
      "job": null
    },
    {
      "id": "39f22369-2875-462c-bf51-62f1238fcf51",
      "created_at": "2026-09-14T05:20:14.979Z",
      "type": "charge",
      "reason": "song",
      "credit_type": "alignment",
      "amount": -1,
      "balance_after": 24,
      "job": {
        "job_id": "8a2073ec-5598-46e9-a05d-dc7a6f01160d",
        "external_id": "TRACK_12345",
        "isrc": "GBLLT2624502"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0xNCAwNToyMDox..."
}
```

## Entry fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique ID of this entry |
| `created_at` | string | When the entry was recorded (ISO 8601, UTC) |
| `type` | string | What kind of entry this is — see below |
| `reason` | string | Charges only: what the credit was spent on — see below |
| `credit_type` | string | The balance this entry belongs to |
| `amount` | number | Credits added (positive) or removed (negative) |
| `balance_after` | number | That credit type's balance immediately after this entry |
| `job` | object \| null | The job this entry belongs to — `job_id`, plus your `external_id` and `isrc` if you sent them. `null` for entries not tied to a job, such as top-ups |

### `type`

| Value | Meaning |
| - | - |
| `charge` | Credits spent. Always negative |
| `refund` | A job's charge returned to you. Positive, and names the job it refunds |
| `top_up` | Credits added to your account |
| `adjustment` | A correction or a transfer between credit types made by our team. Not usage |
| `expiry` | Credits removed because they reached their expiry date |

### `reason` (charges only)

| Value | Meaning |
| - | - |
| `song` | Processing a submitted song — one per song, charged when it is accepted |
| `re_align` | Re-aligning an existing job via [`POST /jobs/{id}/align`](https://docs.lyrcs.ai/api-reference/align-job) |
| `video` | A video product: render, vertical cut or clips |

## Reconciling

* **Balances are per credit type.** `balance_after` tracks the entry's own `credit_type`, so when you hold more than one type, read each type's entries separately. Your plan's type is `credits.plan` on [`GET /usage`](https://docs.lyrcs.ai/api-reference/usage).
* **The newest entry's `balance_after` is your current balance** for that type — the same number as `credits.balance` on `GET /usage`.
* **Opening balance for a period:** take the first entry inside the period and subtract its `amount` from its `balance_after`.
* **Usage for a period:** add up the `charge` entries and subtract the `refund` entries. Leave out `adjustment` entries; they are corrections, not usage.
* `balance_after` is always calculated over your full history, so it is correct on every page and under any filter.

## Paging

Entries are returned oldest first. While `has_more` is `true`, pass `next_cursor` back as `cursor` to get the next page. To pick up new entries later, store the last `created_at` you processed and pass it as `since`. Because `since` is inclusive, you will see that entry again; skip it by `id`.

## Examples

```bash curl theme={null}
curl "https://lyrcs.ai/api/v1/credits/transactions?since=2026-09-01T00:00:00Z&until=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $LYRCS_API_KEY"
```

```javascript Node.js theme={null}
// Every entry for September, across all pages
const entries = [];
let cursor = null;
do {
  const url = new URL("https://lyrcs.ai/api/v1/credits/transactions");
  url.searchParams.set("since", "2026-09-01T00:00:00Z");
  url.searchParams.set("until", "2026-10-01T00:00:00Z");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.LYRCS_API_KEY}` },
  });
  const page = await res.json();
  entries.push(...page.transactions);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

const used = entries
  .filter((e) => e.type === "charge" || e.type === "refund")
  .reduce((sum, e) => sum - e.amount, 0);
console.log(`Credits used in September: ${used}`);
```

```python Python theme={null}
import os, requests

entries, cursor = [], None
while True:
    params = {"since": "2026-09-01T00:00:00Z", "until": "2026-10-01T00:00:00Z"}
    if cursor:
        params["cursor"] = cursor
    page = requests.get(
        "https://lyrcs.ai/api/v1/credits/transactions",
        headers={"Authorization": f"Bearer {os.environ['LYRCS_API_KEY']}"},
        params=params,
    ).json()
    entries += page["transactions"]
    if not page["has_more"]:
        break
    cursor = page["next_cursor"]

used = -sum(e["amount"] for e in entries if e["type"] in ("charge", "refund"))
print(f"Credits used in September: {used}")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.