---
title: "Get transaction history"
canonical_url: https://docs.zvid.io/docs/endpoints/get-transactions/
source: docs/endpoints/get-transactions.api.mdx
content_revision: 6338386a1dd87e4a
---

# Get transaction history

`GET /api/credits/transactions`

Retrieve paginated list of credit transactions

## Authentication

- Option 1: `x-api-key: YOUR_API_KEY` (header). API key for authentication. Create one in your dashboard.
- Option 2: `Authorization: Bearer YOUR_ACCESS_TOKEN`. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.

Create API keys at [app.zvid.io/api-keys](https://app.zvid.io/api-keys). Keep credentials on your server.

## Parameters

| Parameter | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| `page` | query | integer | No | Page number Default: `1`. Minimum: `1`. |
| `limit` | query | integer | No | Number of items per page Default: `20`. Minimum: `1`. Maximum: `100`. |

## Request

The shell examples read credentials from `ZVID_API_KEY` (or `ZVID_ACCESS_TOKEN` for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.

This operation does not take a request body.

### Request example

```bash
curl --request GET 'https://api.zvid.io/api/credits/transactions' \
  --header "x-api-key: $ZVID_API_KEY"
```

## Responses


### HTTP 200

Transaction history retrieved successfully

Content type: `application/json`.

Unknown properties are rejected. Required properties: `transactions`, `pagination`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.transactions` | array of [Transaction](#schema-transaction) | Yes |  |
| `response.pagination` | object | Yes | Unknown properties are rejected. Required properties: `page`, `limit`, `total`, `totalPages`, `hasNext`, `hasPrev`. |

**Nested field: `response.transactions`**

**Array item: `response.transactions[]`**

Schema: [Transaction](#schema-transaction).

**Nested field: `response.pagination`**

Unknown properties are rejected. Required properties: `page`, `limit`, `total`, `totalPages`, `hasNext`, `hasPrev`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.pagination.page` | integer | Yes |  |
| `response.pagination.limit` | integer | Yes |  |
| `response.pagination.total` | integer | Yes |  |
| `response.pagination.totalPages` | integer | Yes |  |
| `response.pagination.hasNext` | boolean | Yes | Whether there are more pages after the current one |
| `response.pagination.hasPrev` | boolean | Yes | Whether there are pages before the current one |


### HTTP 400

Invalid query parameters

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes |  |
| `response.message` | string | No |  |
| `response.details` | array of object | No |  |
| `response.planLimits` | object | No | Present on render validation errors; contains the authenticated user's current render limits. |

**Nested field: `response.details`**

**Array item: `response.details[]`**

Unknown properties are rejected. Required properties: `field`, `message`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.details[].field` | string | Yes |  |
| `response.details[].message` | string | Yes |  |


### HTTP 401

Unauthorized

Content type: `application/json`.

Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 500

Internal server error

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


## Schema definitions

The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.


### schema transaction list

**TransactionList**


Unknown properties are rejected. Required properties: `transactions`, `pagination`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `TransactionList.transactions` | array of [Transaction](#schema-transaction) | Yes |  |
| `TransactionList.pagination` | object | Yes | Unknown properties are rejected. Required properties: `page`, `limit`, `total`, `totalPages`, `hasNext`, `hasPrev`. |

**Nested field: `TransactionList.transactions`**

**Array item: `TransactionList.transactions[]`**

Schema: [Transaction](#schema-transaction).

**Nested field: `TransactionList.pagination`**

Unknown properties are rejected. Required properties: `page`, `limit`, `total`, `totalPages`, `hasNext`, `hasPrev`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `TransactionList.pagination.page` | integer | Yes |  |
| `TransactionList.pagination.limit` | integer | Yes |  |
| `TransactionList.pagination.total` | integer | Yes |  |
| `TransactionList.pagination.totalPages` | integer | Yes |  |
| `TransactionList.pagination.hasNext` | boolean | Yes | Whether there are more pages after the current one |
| `TransactionList.pagination.hasPrev` | boolean | Yes | Whether there are pages before the current one |


### schema transaction

**Transaction**


Unknown properties are rejected. Required properties: `id`, `userId`, `amount`, `transactionType`, `createdAt`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `Transaction.id` | integer | Yes |  |
| `Transaction.userId` | integer | Yes |  |
| `Transaction.amount` | integer | Yes | Transaction amount (positive for additions, negative for deductions) |
| `Transaction.transactionType` | `"earned"` / `"spent"` / `"admin_adjustment"` / `"credit_pack"` / `"revoke"` / `"plan_change_adjustment"` | Yes | Type of transaction |
| `Transaction.creditSource` | `"addon"` / `"subscription"` | No | Credit pool affected by this transaction |
| `Transaction.subscriptionCreditPeriodId` | integer / null | No | Subscription credit period touched by this transaction, if applicable |
| `Transaction.jobId` | string / null | No | Related job ID (if applicable) Format: `uuid`. |
| `Transaction.description` | string | No |  |
| `Transaction.metadata` | object OR string OR null | No | Exactly one of the listed alternatives must match. |
| `Transaction.createdAt` | string | Yes | Format: `date-time`. |

**Nested field: `Transaction.metadata`**

Exactly one of the listed alternatives must match.

**oneOf alternative 1**

Type: object.

**oneOf alternative 2**

Type: string.

**oneOf alternative 3**

Type: null.


### schema validation error

**ValidationError**


Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `ValidationError.error` | string | Yes |  |
| `ValidationError.message` | string | No |  |
| `ValidationError.details` | array of object | No |  |
| `ValidationError.planLimits` | object | No | Present on render validation errors; contains the authenticated user's current render limits. |

**Nested field: `ValidationError.details`**

**Array item: `ValidationError.details[]`**

Unknown properties are rejected. Required properties: `field`, `message`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `ValidationError.details[].field` | string | Yes |  |
| `ValidationError.details[].message` | string | Yes |  |


### schema authentication error

**AuthenticationError**


Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `AuthenticationError.error` | string | Yes | Error type |
| `AuthenticationError.message` | string | No | Human-readable error message |


### schema error

**Error**


Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `Error.error` | string | Yes | Error type |
| `Error.message` | string | No | Human-readable error message |


## Related resources

- [OpenAPI specification](https://docs.zvid.io/openapi.yaml)
- [Project payload schema](https://docs.zvid.io/schemas/render-payload.schema.json)
- [Quick Start](https://docs.zvid.io/docs/quick-start/)
- [Authentication guide](https://docs.zvid.io/docs/authentication/)