---
title: "Credit balance and transaction history"
method: GET
path: "/v1/credits"
tags: ["billing"]
---

# Credit balance and transaction history

`GET /v1/credits`

## Request

- Base URL: `https://api.primateintelligence.ai`
- URL: `https://api.primateintelligence.ai/v1/credits`
- Auth: HTTP bearer

Agent-facing billing truth (PRI-480 A-5): remaining balance in billable seconds plus a paginated ledger. Check this before submitting work to avoid a 402. Requires the billing:read scope.

## Query parameters

- `limit` integer: Transactions per page (1–100, default 20).
- `before` string: Cursor — return transactions older than this id.

## Response `200`

Balance plus one page of ledger entries.

- CreditsResponse
  - `object` 'credits', required
  - `balance_seconds` number, required: The authoritative credit balance (legacy field name retained for backward compatibility).
  - `grant_seconds` number, nullable, required: Original signup grant, when one exists.
  - `used_seconds` number, nullable, required: Consumed against the signup grant (grant minus balance).
  - `transactions` CreditTransaction[], required
    - `id` string, required
    - `kind` string, required: e.g. signup_grant, analysis_debit, stream_debit, purchase.
    - `seconds_delta` number, required: Signed: negative debits, positive credits.
    - `balance_after_seconds` number, required
    - `source_type` string, nullable, required
    - `source_id` string, nullable, required
    - `created_at` string, required
  - `has_more` boolean, required

## Other responses

- `400`: validation_failed / url_forbidden / prompt errors (§15)
- `401`: invalid_api_key / key_revoked / key_expired
- `404`: resource_not_found (account-scoped; no existence oracle)
- `409`: resource_conflict / idempotency_key_reused / idempotency_unavailable
- `429`: rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After)

---

[API](https://skmtc.dev/primateintelligence/apis/primate-vision-api.md) · [All operations](https://skmtc.dev/primateintelligence/apis/primate-vision-api/llms.txt) · [OpenAPI document](https://skmtc.dev/primateintelligence/apis/primate-vision-api/revisions/aa51b01dc8ad?raw)