Skip to main content
GET
/
pictoryapis
/
v1
/
aicredits
/
usage
Get AI Credits Usage
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/aicredits/usage \
  --header 'Authorization: <authorization>'
[
  {
    "transactionId": "20260508153648354912f9ebd4ef94b1baa469ae1179a3ead",
    "type": "debit",
    "amount": 0.6,
    "source": "Text-to-Image",
    "description": "Credits consumed by a text-to-image generation",
    "plan": "API Annual",
    "transactionDate": "2026-05-08T15:37:11.176Z"
  },
  {
    "transactionId": "20260501101259445721a0a11c9594db9b2577c844bc7338e",
    "type": "credit",
    "amount": 100,
    "source": "Monthly Reset",
    "description": "Credits reset at the start of the billing cycle",
    "plan": "API Annual",
    "transactionDate": "2026-05-01T10:12:59.445Z"
  },
  {
    "transactionId": "20260305072219568c7b29f4c37ea4c41a49e89b5dba408f2",
    "type": "debit",
    "amount": 30,
    "source": "AI Avatar",
    "description": "Credits consumed by an AI avatar generation",
    "plan": "Professional Annual",
    "transactionDate": "2026-03-05T07:33:32.217Z"
  }
]

​
Overview

Retrieve a per-transaction ledger of AI credit activity on your subscription. Each entry represents a single event that affected your AI credit balance, such as credits consumed by an AI avatar generation or credits added by purchasing an add-on. By default, this endpoint returns transactions for the current month. You can query a specific month using the optional query parameters described below. Transactions are returned in descending order by date (newest first). Use this endpoint to power a credit usage dashboard, generate billing reports, or audit consumption against expected workloads.
You need a valid API key to use this endpoint. Get your API key from the API Access page in your Pictory dashboard.
Usage history is available for the last 12 months only. Older transactions are not retained.

​
API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/aicredits/usage

​
Request Parameters

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

​
Query Parameters

​
year
integer
The year to query (for example, 2026). When omitted, the current year is used.Note: year cannot be passed without month. Year-only queries are not supported.
​
month
integer
The month to query, between 1 and 12. When omitted, the current month is used.When month is provided without year, the current year is assumed.

​
Query Behavior

RequestReturns
GET /aicredits/usageAll transactions for the current month
GET /aicredits/usage?month=2February of the current year
GET /aicredits/usage?year=2026&month=3March 2026
GET /aicredits/usage?year=2026 (no month)400 INVALID_REQUEST — month is required when year is provided

​
Response

Returns an array of transaction objects. Each transaction describes a single AI credit event with its direction (credit or debit), amount, and source.
​
transactions
array of objects
required
Array of transaction objects, ordered by transaction date in descending order (newest first). The response body is the array itself.

​
Response Examples

[
  {
    "transactionId": "20260508153648354912f9ebd4ef94b1baa469ae1179a3ead",
    "type": "debit",
    "amount": 0.6,
    "source": "Text-to-Image",
    "description": "Credits consumed by a text-to-image generation",
    "plan": "API Annual",
    "transactionDate": "2026-05-08T15:37:11.176Z"
  },
  {
    "transactionId": "20260501101259445721a0a11c9594db9b2577c844bc7338e",
    "type": "credit",
    "amount": 100,
    "source": "Monthly Reset",
    "description": "Credits reset at the start of the billing cycle",
    "plan": "API Annual",
    "transactionDate": "2026-05-01T10:12:59.445Z"
  },
  {
    "transactionId": "20260305072219568c7b29f4c37ea4c41a49e89b5dba408f2",
    "type": "debit",
    "amount": 30,
    "source": "AI Avatar",
    "description": "Credits consumed by an AI avatar generation",
    "plan": "Professional Annual",
    "transactionDate": "2026-03-05T07:33:32.217Z"
  }
]

​
Code Examples

Replace YOUR_API_KEY with your actual API key that starts with pictai_
# Current month
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/aicredits/usage' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

# Specific month
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/aicredits/usage?year=2026&month=3' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool