> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get AI Credits Usage

> Retrieve a transaction-level history of AI credit consumption and additions for your subscription

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

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

<Note>
  Usage history is available for the **last 12 months only**. Older transactions are not retained.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/aicredits/usage
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

### Query Parameters

<ParamField query="year" type="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.
</ParamField>

<ParamField query="month" type="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.
</ParamField>

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

<ResponseField name="transactions" type="array of objects" required>
  Array of transaction objects, ordered by transaction date in descending order (newest first). The response body is the array itself.

  <Expandable title="transaction object">
    <ResponseField name="transactionId" type="string" required>
      Unique identifier for this transaction.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      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)
    </ResponseField>

    <ResponseField name="amount" type="number" required>
      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).
    </ResponseField>

    <ResponseField name="source" type="string" required>
      Human-readable label describing the cause of the transaction. Example values include:

      * `AI Avatar` — credits consumed by an AI avatar generation
      * `Text-to-Image` — credits consumed by a text-to-image generation
      * `AI Video` — credits consumed by an AI video generation
      * `Courtesy Credits` — complimentary credits added to your account
      * `Add-on Purchase` — credits added by purchasing a credits add-on
      * `Promotional Credits` — credits added through a promotional campaign
      * `Monthly Reset` — credits reset at the start of a billing cycle
      * `Plan Change` — credits adjusted due to a subscription plan change
      * `Refund` — credits refunded after a failed operation
    </ResponseField>

    <ResponseField name="description" type="string">
      Plain-language description of the transaction source. May be `null` for unknown sources.
    </ResponseField>

    <ResponseField name="plan" type="string">
      Subscription plan in effect at the time of the transaction. Example values:

      * `Professional Annual`
      * `API Annual`
      * `API Monthly`
      * `Teams Annual`
      * `Free Trial`

      Unrecognized plans fall back to the raw internal plan code.
    </ResponseField>

    <ResponseField name="transactionDate" type="string">
      ISO 8601 timestamp of when the transaction occurred (UTC).
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "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"
    }
  ]
  ```

  ```json 200 - Empty Results theme={null}
  []
  ```

  ```json 400 - Invalid Query Parameter theme={null}
  {
    "code": "INVALID_REQUEST",
    "message": "Query param 'year' must be a valid integer."
  }
  ```

  ```json 400 - Invalid Month theme={null}
  {
    "code": "BAD_REQUEST",
    "message": "Invalid month. Month must be between 1 and 12."
  }
  ```

  ```json 400 - Out of Window theme={null}
  {
    "code": "BAD_REQUEST",
    "message": "Usage history is only available for the last 12 months."
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "code": "BAD_CONFIGURATION",
    "message": "An unexpected error occurred while processing the request"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  # 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
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```javascript JavaScript / Node.js theme={null}
  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 PHP theme={null}
  <?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";
  }
  ?>
  ```

  ```go Go theme={null}
  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)
      }
  }
  ```
</CodeGroup>