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

# List Consumption

> Retrieve a paginated list of AI credit consumption line items with filtering

Returns a paginated list of AI credit consumption line items — one row per provider run — equivalent to the dashboard **Consumption Breakdown** export. Each line includes the credits used, the USD equivalent under your account rate, the provider and service, the requestor who created the order, and the requestor's program tags.

<Note>
  This endpoint is restricted to **account owners and billing managers**. The API key must belong to a user with the `client_owner` or `client_accessBillings` role, otherwise the request is rejected with `403`.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api-integration.ollang.com/integration/consumption?pageOptions[page]=1&pageOptions[take]=10&pageOptions[orderBy]=occurredAt&pageOptions[orderDirection]=desc" \
    -H "X-Api-Key: <your-api-key>"
  ```

  ```bash cURL with filters theme={null}
  curl -X GET "https://api-integration.ollang.com/integration/consumption" \
    -H "X-Api-Key: <your-api-key>" \
    -G \
    -d "pageOptions[page]=1" \
    -d "pageOptions[take]=20" \
    -d "filter[from]=2026-01-01T00:00:00Z" \
    -d "filter[to]=2026-01-31T23:59:59Z" \
    -d "filter[provider]=elevenlabs" \
    -d "filter[orderType]=document" \
    -d "filter[createdBy]=jane@acme.com" \
    -d "filter[tag]=Energy Studio"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    "pageOptions[page]": "1",
    "pageOptions[take]": "10",
    "pageOptions[orderBy]": "occurredAt",
    "pageOptions[orderDirection]": "desc",
  });

  const response = await fetch(
    `https://api-integration.ollang.com/integration/consumption?${params}`,
    {
      method: "GET",
      headers: {
        "X-Api-Key": "<your-api-key>",
      },
    }
  );
  ```

  ```javascript JavaScript with filters theme={null}
  const params = new URLSearchParams({
    "pageOptions[page]": "1",
    "pageOptions[take]": "20",
    "filter[from]": "2026-01-01T00:00:00Z",
    "filter[to]": "2026-01-31T23:59:59Z",
    "filter[provider]": "elevenlabs",
    "filter[orderType]": "document",
    "filter[createdBy]": "jane@acme.com",
    "filter[tag]": "Energy Studio",
  });

  const response = await fetch(
    `https://api-integration.ollang.com/integration/consumption?${params}`,
    {
      headers: {
        "X-Api-Key": "<your-api-key>",
      },
    }
  );
  ```

  ```python Python theme={null}
  import requests

  params = {
      'pageOptions[page]': 1,
      'pageOptions[take]': 10,
      'pageOptions[orderBy]': 'occurredAt',
      'pageOptions[orderDirection]': 'desc'
  }

  headers = {
      'X-Api-Key': '<your-api-key>'
  }

  response = requests.get(
      'https://api-integration.ollang.com/integration/consumption',
      params=params,
      headers=headers
  )
  ```

  ```python Python with filters theme={null}
  import requests

  params = {
      'pageOptions[page]': 1,
      'pageOptions[take]': 20,
      'filter[from]': '2026-01-01T00:00:00Z',
      'filter[to]': '2026-01-31T23:59:59Z',
      'filter[provider]': 'elevenlabs',
      'filter[orderType]': 'document',
      'filter[createdBy]': 'jane@acme.com',
      'filter[tag]': 'Energy Studio'
  }

  headers = {
      'X-Api-Key': '<your-api-key>'
  }

  response = requests.get(
      'https://api-integration.ollang.com/integration/consumption',
      params=params,
      headers=headers
  )
  ```

  ```php PHP theme={null}
  $params = http_build_query([
      'pageOptions' => [
          'page' => 1,
          'take' => 10,
          'orderBy' => 'occurredAt',
          'orderDirection' => 'desc'
      ]
  ]);

  $curl = curl_init();

  curl_setopt_array($curl, array(
      CURLOPT_URL => 'https://api-integration.ollang.com/integration/consumption?' . $params,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
          'X-Api-Key: <your-api-key>'
      ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "net/http"
      "net/url"
  )

  func main() {
      baseURL := "https://api-integration.ollang.com/integration/consumption"

      params := url.Values{}
      params.Add("pageOptions[page]", "1")
      params.Add("pageOptions[take]", "10")
      params.Add("pageOptions[orderBy]", "occurredAt")
      params.Add("pageOptions[orderDirection]", "desc")

      req, _ := http.NewRequest("GET", baseURL + "?" + params.Encode(), nil)
      req.Header.Set("X-Api-Key", "<your-api-key>")

      client := &http.Client{}
      resp, _ := client.Do(req)
  }
  ```

  ```java Java theme={null}
  String params = "pageOptions[page]=1&pageOptions[take]=10&pageOptions[orderBy]=occurredAt&pageOptions[orderDirection]=desc";

  HttpResponse<String> response = Unirest.get("https://api-integration.ollang.com/integration/consumption?" + params)
    .header("X-Api-Key", "<your-api-key>")
    .asString();
  ```
</RequestExample>

## Authorizations

This endpoint requires API key authentication. Include your API key in the request header:

* **Header name**: `X-Api-Key`
* **Header value**: Your API key from the Ollang dashboard
* **Format**: `X-Api-Key: your-api-key-here`

You can obtain your API key from your [Ollang dashboard](https://lab.ollang.com).

The key must belong to a user with the `client_owner` or `client_accessBillings` role. Requests from keys without one of these billing roles are rejected with `403`.

## Query Parameters

### Pagination Parameters

<ParamField query="pageOptions[page]" type="number" default="1">
  The page number to retrieve. Must be 1 or greater.
</ParamField>

<ParamField query="pageOptions[take]" type="number" default="10">
  The number of items per page. Must be between 1 and 50.
</ParamField>

### Sorting Parameters

<ParamField query="pageOptions[orderBy]" type="string" default="id">
  The field to sort the results by. Common values: `occurredAt`, `creditsUsed`,
  `provider`.
</ParamField>

<ParamField query="pageOptions[orderDirection]" type="string" default="desc">
  The direction to sort the results. Options: `asc`, `desc`.
</ParamField>

### Search Parameters

<ParamField query="pageOptions[search]" type="string">
  A search term to filter the results across relevant fields.
</ParamField>

### Filter Parameters

<ParamField query="filter[search]" type="string">
  Search by order name (case-insensitive contains).
</ParamField>

<ParamField query="filter[from]" type="string">
  Include consumption from this date onward (inclusive, ISO 8601 format).
</ParamField>

<ParamField query="filter[to]" type="string">
  Include consumption up to this date (inclusive, ISO 8601 format).
</ParamField>

<ParamField query="filter[provider]" type="string">
  Filter by provider key, for example `openai`, `gemini`, or `elevenlabs`. Use
  the `providerKey` value returned on each line item.
</ParamField>

<ParamField query="filter[orderType]" type="string">
  Filter by order type. Values: `cc`, `subtitle`, `document`, `aiDubbing`,
  `studioDubbing`, `proofreading`, `other`, `revision` (see
  [Order Types](/apis/ollang-api-reference/order-types)).
</ParamField>

<ParamField query="filter[createdBy]" type="string">
  Filter by requestor. Accepts a user id or an email address.
</ParamField>

<ParamField query="filter[orderId]" type="string">
  Filter by a single order id.
</ParamField>

<ParamField query="filter[tag]" type="string">
  Filter by a single program tag value, for example `Energy Studio`.
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of consumption line items — one row per provider run.

  <Expandable title="Consumption Line Item Properties">
    <ResponseField name="id" type="string">
      Stable consumption line id.
    </ResponseField>

    <ResponseField name="orderId" type="string">
      Id of the order this consumption line belongs to.
    </ResponseField>

    <ResponseField name="orderName" type="string">
      Display name of the order.
    </ResponseField>

    <ResponseField name="createdBy" type="object">
      The requestor who created the order.

      <Expandable title="Created By Properties">
        <ResponseField name="id" type="string">
          Requestor user id.
        </ResponseField>

        <ResponseField name="name" type="string">
          Requestor full name.
        </ResponseField>

        <ResponseField name="email" type="string">
          Requestor email address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="orderType" type="string">
      Type of the order. Possible values: `cc`, `subtitle`, `document`, `aiDubbing`,
      `studioDubbing`, `proofreading`, `other`, `revision`.
    </ResponseField>

    <ResponseField name="creditsUsed" type="number">
      Credits consumed for this line. Unit: credits.
    </ResponseField>

    <ResponseField name="usdEquivalent" type="number">
      USD equivalent under the account commercial rate (credits / 1000). Unit: USD.
    </ResponseField>

    <ResponseField name="provider" type="string">
      Provider display name (for example `Elevenlabs`).
    </ResponseField>

    <ResponseField name="providerKey" type="string">
      Raw provider key used for filtering (for example `elevenlabs`).
    </ResponseField>

    <ResponseField name="service" type="string">
      Service / pipeline stage (for example `Text to Speech`).
    </ResponseField>

    <ResponseField name="tags" type="array">
      Program tags of the requestor.
    </ResponseField>

    <ResponseField name="occurredAt" type="string">
      ISO 8601 timestamp of when the consumption occurred.
    </ResponseField>

    <ResponseField name="projectId" type="string">
      Id of the project the order belongs to. Optional.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata.

  <Expandable title="Meta Object Properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="take" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="itemCount" type="number">
      Total number of items across all pages.
    </ResponseField>

    <ResponseField name="pageCount" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasNextPage" type="boolean">
      Whether there is a next page available.
    </ResponseField>

    <ResponseField name="hasPreviousPage" type="boolean">
      Whether there is a previous page available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "cons_60b8d6f1e1b9b1d8c6c0d8e1",
        "orderId": "60b8d6f1e1b9b1d8c6c0d8e1",
        "orderName": "Sample Project - Episode 1",
        "createdBy": {
          "id": "user_abc123",
          "name": "Jane Doe",
          "email": "jane@acme.com"
        },
        "orderType": "document",
        "creditsUsed": 9923,
        "usdEquivalent": 9.92,
        "provider": "Elevenlabs",
        "providerKey": "elevenlabs",
        "service": "Text to Speech",
        "tags": ["Energy Studio"],
        "occurredAt": "2026-01-15T10:30:00Z",
        "projectId": "proj_xyz789"
      }
    ],
    "meta": {
      "page": 1,
      "take": 10,
      "itemCount": 1,
      "pageCount": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Access denied",
    "message": "The API key user lacks the client_owner or client_accessBillings role",
    "code": "ACCESS_DENIED"
  }
  ```
</ResponseExample>