List the credit movements

About

Use this to explain the balance that get_credits (GET /v1/credits) shows: what was charged and for which project, what came back, what was bought. Movements come newest first; send nextCursor as cursor to read older ones. Filter with period to read one calendar month; top-ups and their reversals belong to no month, so a period filter leaves them out. A movement the API bonus paid has credits 0, and fromBonus says how much the bonus moved; receiving the bonus is not a movement. The history starts when the ledger was turned on, and opening_balance movements sum up what came before. The balance that counts is the one of get_credits.

Example use

An agency that gives each client its own API key reads the credit movements at the end of each week. It adds up the charges and refunds of each keyId and puts the total in the weekly report of that client.

Endpoint

GET https://api.gpt-video.com/v1/credits/ledger

• Scope clips:read.
• Rate limit 120 requests a minute for each key and 240 for each account, shared by every read call. See rate limits.
• No Idempotency-Key.

Parameters

Query

Request

List the latest credit movements.

curl "https://api.gpt-video.com/v1/credits/ledger?limit=10" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"

const res = await fetch("https://api.gpt-video.com/v1/credits/ledger?limit=10", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/credits/ledger?limit=10",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)

{
  "method": "tools/call",
  "params": {
    "name": "list_ledger_entries",
    "arguments": {
      "limit": 10
    }
  }
}

Response

A successful call answers HTTP 200.

Fields to check

Response example

{
  "data": [
    {
      "id": "lgr_9b1e4c7a2d5f40e8a316",
      "kind": "charge",
      "operation": "analysis",
      "credits": -30,
      "fromPlan": -30,
      "fromTopUp": 0,
      "fromBonus": 0,
      "projectId": "prj_7c2e9a4f1b3d4e8096a5",
      "source": "api",
      "keyId": "mck_5f2c9e1a7b3d8046",
      "period": "2026-09",
      "createdAt": "2026-09-01T09:10:00.000Z"
    },
    {
      "id": "lgr_2c8f0a6e4b1d47c9e5a0",
      "kind": "top_up",
      "operation": null,
      "credits": 250,
      "fromPlan": 0,
      "fromTopUp": 250,
      "fromBonus": 0,
      "projectId": null,
      "source": "system",
      "keyId": null,
      "period": null,
      "createdAt": "2026-09-01T08:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

{
  "data": [
    {
      "id": "lgr_9b1e4c7a2d5f40e8a316",
      "kind": "charge",
      "operation": "analysis",
      "credits": -30,
      "fromPlan": -30,
      "fromTopUp": 0,
      "fromBonus": 0,
      "projectId": "prj_7c2e9a4f1b3d4e8096a5",
      "source": "api",
      "keyId": "mck_5f2c9e1a7b3d8046",
      "period": "2026-09",
      "createdAt": "2026-09-01T09:10:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

{
  "data": [
    {
      "id": "lgr_5d8a2f0c7e1b46a9d3c7",
      "kind": "charge",
      "operation": "export",
      "credits": 0,
      "fromPlan": 0,
      "fromTopUp": 0,
      "fromBonus": -1,
      "projectId": null,
      "source": "api",
      "keyId": "mck_5f2c9e1a7b3d8046",
      "period": "2026-09",
      "createdAt": "2026-09-01T09:42:00.000Z"
    },
    {
      "id": "lgr_0f6c3b9e2a7d41f8c5b1",
      "kind": "charge",
      "operation": "assistant",
      "credits": 0,
      "fromPlan": 0,
      "fromTopUp": 0,
      "fromBonus": -2,
      "projectId": null,
      "source": "api",
      "keyId": "mck_5f2c9e1a7b3d8046",
      "period": "2026-09",
      "createdAt": "2026-09-01T09:40:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The cursor is not valid. Send the nextCursor of the previous page unchanged, or leave it out.",
    "hint": "Fix the request as the message says, then send it again.",
    "requestId": "req_7d2a9c4e1b6f3a0d8e5c2b71"
  }
}

Errors

Every call can also answer these errors. VALIDATION_FAILED, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used.

Related operations

• get_credits (GET /v1/credits) Get the credit balance

Questions

Why is a top-up missing when I filter by month?

Top-ups and their reversals belong to no month, so a period filter leaves them out. Read the list without period to see them.

Does the sum of the movements give my balance?

Use get_credits (GET /v1/credits) for the balance. This list explains how it moved, and it is in beta while it runs next to the counters it explains.

Why does a movement have no keyId?

keyId names the API key that made the call. Movements made in the GPT-Video app, by a purchase, or by an assistant connected without a key have none.

Why is there no movement for the API bonus I received?

Receiving the bonus does not change the spendable balance. get_credits (GET /v1/credits) shows the bonus, and every charge it pays is listed here with credits 0 and the amount in fromBonus.

View as Markdown