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

# Consumption Events - List

> Retrieve a paginated list of consumption events for your organization

<Note>
  Este endpoint requiere autenticacion. Inclui tu API key en el header `Authorization: Bearer <API_KEY>`. Ver [Autenticacion](/api-reference/authentication) para mas detalles.
</Note>

Returns a paginated list of consumption events for the authenticated organization. Use this endpoint to:

* Browse individual consumption events with full detail
* Filter by date range, agent, feature, provider, model, or conversation
* Sort by date or credits charged
* Paginate through large result sets

### Query Parameters

#### Optional

<ParamField query="startDate" type="string (ISO 8601)">
  Filter events that occurred on or after this date. Must be a valid ISO 8601 datetime string (e.g. `2025-01-01T00:00:00.000Z`).
</ParamField>

<ParamField query="endDate" type="string (ISO 8601)">
  Filter events that occurred on or before this date. Must be a valid ISO 8601 datetime string. Must be greater than or equal to `startDate` if both are provided.
</ParamField>

<ParamField query="agentId" type="string">
  Filter events by a specific agent ID.
</ParamField>

<ParamField query="feature" type="string">
  Filter events by feature name (e.g. `chat`, `transcription`).
</ParamField>

<ParamField query="provider" type="string">
  Filter events by AI provider (e.g. `openai`, `anthropic`).
</ParamField>

<ParamField query="modelName" type="string">
  Filter events by model name (e.g. `gpt-4`, `claude-3-opus`).
</ParamField>

<ParamField query="conversationId" type="string">
  Filter events by conversation ID.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Minimum value: `1`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of events per page. Minimum: `1`, maximum: `100`.
</ParamField>

<ParamField query="orderBy" type="string" default="occurredAt_desc">
  Sort order for results. Valid values: `occurredAt_asc`, `occurredAt_desc`, `creditsCharged_asc`, `creditsCharged_desc`.
</ParamField>

### Response

<ResponseField name="data" type="array">
  List of consumption events.

  <Expandable title="Consumption event object" defaultOpen>
    <ResponseField name="id" type="string">
      Unique identifier of the consumption event.
    </ResponseField>

    <ResponseField name="organizationId" type="string">
      ID of the organization that owns this event.
    </ResponseField>

    <ResponseField name="agentId" type="string">
      ID of the agent that generated this event.
    </ResponseField>

    <ResponseField name="feature" type="string">
      The feature that triggered the consumption (e.g. `chat`, `transcription`).
    </ResponseField>

    <ResponseField name="provider" type="string">
      The AI provider used (e.g. `openai`, `anthropic`).
    </ResponseField>

    <ResponseField name="modelName" type="string">
      The model name used (e.g. `gpt-4`, `claude-3-opus`).
    </ResponseField>

    <ResponseField name="inputTokens" type="integer">
      Number of input tokens consumed.
    </ResponseField>

    <ResponseField name="outputTokens" type="integer">
      Number of output tokens generated.
    </ResponseField>

    <ResponseField name="units" type="number">
      Number of units consumed (for non-token-based features).
    </ResponseField>

    <ResponseField name="creditsCharged" type="number">
      Final credits charged after applying the billing coefficient.
    </ResponseField>

    <ResponseField name="creditsChargedRaw" type="number">
      Raw credits before billing coefficient adjustment.
    </ResponseField>

    <ResponseField name="billingCoefficient" type="number">
      Multiplier applied to raw credits to calculate the final charge.
    </ResponseField>

    <ResponseField name="occurredAt" type="string (ISO 8601)">
      Timestamp when the consumption event occurred.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Additional metadata associated with the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      ID of the conversation that generated this event (if applicable).
    </ResponseField>

    <ResponseField name="messageId" type="string">
      ID of the message that generated this event (if applicable).
    </ResponseField>

    <ResponseField name="agent" type="object">
      Agent summary.

      <Expandable title="Agent object">
        <ResponseField name="id" type="string">
          Agent ID.
        </ResponseField>

        <ResponseField name="name" type="string">
          Agent name.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

  <Expandable title="Pagination object" defaultOpen>
    <ResponseField name="page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Number of items per page.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of matching events.
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages.
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

| Status Code | Type             | Description                       |
| ----------- | ---------------- | --------------------------------- |
| 400         | INVALID\_REQUEST | `startDate` is after `endDate`    |
| 401         | UNAUTHORIZED     | Missing or invalid authentication |

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request GET 'https://dashboard.laburen.com/api/consumption-events?startDate=2025-01-01T00:00:00.000Z&endDate=2025-01-31T23:59:59.000Z&page=1&limit=20&orderBy=occurredAt_desc' \
  --header 'Authorization: Bearer <API_KEY>'
  ```

  ```javascript JavaScript theme={null}
  const apiUrl = 'https://dashboard.laburen.com/api';
  const apiKey = '<API_KEY>';

  const params = new URLSearchParams({
    startDate: '2025-01-01T00:00:00.000Z',
    endDate: '2025-01-31T23:59:59.000Z',
    page: '1',
    limit: '20',
    orderBy: 'occurredAt_desc',
  });

  const response = await fetch(`${apiUrl}/consumption-events?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
    },
  });

  const data = await response.json();
  console.log(data);
  ```

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

  api_url = "https://dashboard.laburen.com/api"
  api_key = "<API_KEY>"

  response = requests.get(
      f"{api_url}/consumption-events",
      headers={
          "Authorization": f"Bearer {api_key}",
      },
      params={
          "startDate": "2025-01-01T00:00:00.000Z",
          "endDate": "2025-01-31T23:59:59.000Z",
          "page": 1,
          "limit": 20,
          "orderBy": "occurredAt_desc",
      },
  )

  data = response.json()
  print(data)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "clxxxxxxxxxxxxxxxxx",
        "organizationId": "clxxxxxxxxxxxxxxxxx",
        "agentId": "clxxxxxxxxxxxxxxxxx",
        "feature": "chat",
        "provider": "openai",
        "modelName": "gpt-4",
        "inputTokens": 1250,
        "outputTokens": 430,
        "units": null,
        "creditsCharged": 0.0285,
        "creditsChargedRaw": 0.0285,
        "billingCoefficient": 1.0,
        "occurredAt": "2025-01-15T14:32:10.000Z",
        "metadata": {},
        "conversationId": "clxxxxxxxxxxxxxxxxx",
        "messageId": "clxxxxxxxxxxxxxxxxx",
        "agent": {
          "id": "clxxxxxxxxxxxxxxxxx",
          "name": "Support Bot"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 154,
      "totalPages": 8
    }
  }
  ```
</ResponseExample>