Get AI Credits Usage
curl --request GET \
--url https://api.pictory.ai/pictoryapis/v1/aicredits/usage \
--header 'Authorization: <authorization>'import requests
url = "https://api.pictory.ai/pictoryapis/v1/aicredits/usage"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.pictory.ai/pictoryapis/v1/aicredits/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v1/aicredits/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.pictory.ai/pictoryapis/v1/aicredits/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.pictory.ai/pictoryapis/v1/aicredits/usage")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pictory.ai/pictoryapis/v1/aicredits/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body[
{
"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": "INVALID_REQUEST",
"message": "Query param 'year' must be a valid integer."
}
{
"code": "BAD_REQUEST",
"message": "Invalid month. Month must be between 1 and 12."
}
{
"code": "BAD_REQUEST",
"message": "Usage history is only available for the last 12 months."
}
{
"message": "Unauthorized"
}
{
"code": "BAD_CONFIGURATION",
"message": "An unexpected error occurred while processing the request"
}
Account & Usage
Get AI Credits Usage
Retrieve a transaction-level history of AI credit consumption and additions for your subscription
GET
/
pictoryapis
/
v1
/
aicredits
/
usage
Get AI Credits Usage
curl --request GET \
--url https://api.pictory.ai/pictoryapis/v1/aicredits/usage \
--header 'Authorization: <authorization>'import requests
url = "https://api.pictory.ai/pictoryapis/v1/aicredits/usage"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.pictory.ai/pictoryapis/v1/aicredits/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pictory.ai/pictoryapis/v1/aicredits/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.pictory.ai/pictoryapis/v1/aicredits/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.pictory.ai/pictoryapis/v1/aicredits/usage")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pictory.ai/pictoryapis/v1/aicredits/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body[
{
"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": "INVALID_REQUEST",
"message": "Query param 'year' must be a valid integer."
}
{
"code": "BAD_REQUEST",
"message": "Invalid month. Month must be between 1 and 12."
}
{
"code": "BAD_REQUEST",
"message": "Usage history is only available for the last 12 months."
}
{
"message": "Unauthorized"
}
{
"code": "BAD_CONFIGURATION",
"message": "An unexpected error occurred while processing the request"
}
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
API key for authentication (starts with
pictai_)Authorization: YOUR_API_KEY
Query Parameters
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.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
| Request | Returns |
|---|---|
GET /aicredits/usage | All transactions for the current month |
GET /aicredits/usage?month=2 | February of the current year |
GET /aicredits/usage?year=2026&month=3 | March 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.
Array of transaction objects, ordered by transaction date in descending order (newest first). The response body is the array itself.
Show transaction object
Show transaction object
Unique identifier for this transaction.
Direction of the transaction. One of:
debit: AI credits were consumed (for example, an AI avatar generation)credit: AI credits were added to your balance (for example, an add-on purchase)
Always-positive number of AI credits affected by this transaction. The direction is conveyed by
type. May be a decimal (for example, 0.6 for a single Text-to-Image generation).Human-readable label describing the cause of the transaction. Example values include:
AI Avatar: credits consumed by an AI avatar generationText-to-Image: credits consumed by a text-to-image generationAI Video: credits consumed by an AI video generationCourtesy Credits: complimentary credits added to your accountAdd-on Purchase: credits added by purchasing a credits add-onPromotional Credits: credits added through a promotional campaignMonthly Reset: credits reset at the start of a billing cyclePlan Change: credits adjusted due to a subscription plan changeRefund: credits refunded after a failed operation
Plain-language description of the transaction source. May be
null for unknown sources.Subscription plan in effect at the time of the transaction. Example values:
Professional AnnualAPI AnnualAPI MonthlyTeams AnnualFree Trial
ISO 8601 timestamp of when the transaction occurred (UTC).
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": "INVALID_REQUEST",
"message": "Query param 'year' must be a valid integer."
}
{
"code": "BAD_REQUEST",
"message": "Invalid month. Month must be between 1 and 12."
}
{
"code": "BAD_REQUEST",
"message": "Usage history is only available for the last 12 months."
}
{
"message": "Unauthorized"
}
{
"code": "BAD_CONFIGURATION",
"message": "An unexpected error occurred while processing the request"
}
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
import requests
url = "https://api.pictory.ai/pictoryapis/v1/aicredits/usage"
headers = {
"Authorization": "YOUR_API_KEY",
"accept": "application/json"
}
params = {"year": 2026, "month": 3}
response = requests.get(url, headers=headers, params=params)
transactions = response.json()
for t in transactions:
direction = "+" if t["type"] == "credit" else "-"
print(f"{t['transactionDate'][:10]} {direction}{t['amount']:>6} {t['source']}")
const response = await fetch(
"https://api.pictory.ai/pictoryapis/v1/aicredits/usage?year=2026&month=3",
{
method: "GET",
headers: {
Authorization: "YOUR_API_KEY",
accept: "application/json",
},
}
);
const transactions = await response.json();
transactions.forEach((t) => {
const direction = t.type === "credit" ? "+" : "-";
console.log(`${t.transactionDate.slice(0, 10)} ${direction}${t.amount} ${t.source}`);
});
<?php
$url = 'https://api.pictory.ai/pictoryapis/v1/aicredits/usage?year=2026&month=3';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: YOUR_API_KEY',
'accept: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
throw new Exception('Request failed with status ' . $httpCode);
}
$transactions = json_decode($response, true);
foreach ($transactions as $t) {
$direction = $t['type'] === 'credit' ? '+' : '-';
echo substr($t['transactionDate'], 0, 10) . " {$direction}{$t['amount']} {$t['source']}\n";
}
?>
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
type Transaction struct {
TransactionID string `json:"transactionId"`
Type string `json:"type"`
Amount float64 `json:"amount"`
Source string `json:"source"`
Description string `json:"description"`
Plan string `json:"plan"`
TransactionDate string `json:"transactionDate"`
}
func main() {
req, _ := http.NewRequest("GET", "https://api.pictory.ai/pictoryapis/v1/aicredits/usage?year=2026&month=3", nil)
req.Header.Set("Authorization", "YOUR_API_KEY")
req.Header.Set("accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var transactions []Transaction
json.Unmarshal(body, &transactions)
for _, t := range transactions {
direction := "-"
if t.Type == "credit" {
direction = "+"
}
fmt.Printf("%s %s%.0f %s\n", t.TransactionDate[:10], direction, t.Amount, t.Source)
}
}
Was this page helpful?
⌘I
