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. 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

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	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.

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.

TransactionList

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

Field	Type	Required	Description and constraints
TransactionList.transactions	array of 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.

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

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.

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

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

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
• Project payload schema
• Quick Start
• Authentication guide