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

> Get aggregated consumption metrics grouped by entity or time period

<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 aggregated consumption metrics for the authenticated organization. Use this endpoint to:

* Get total credits, tokens, and event counts grouped by agent, feature, provider, or model
* Analyze consumption trends over time by grouping by day, week, or month
* Filter aggregations by agent, feature, or provider

### Query Parameters

#### Required

<ParamField query="startDate" type="string (ISO 8601)" required>
  Start of the date range. Must be a valid ISO 8601 datetime string (e.g. `2025-01-01T00:00:00.000Z`). Must be before `endDate`.
</ParamField>

<ParamField query="endDate" type="string (ISO 8601)" required>
  End of the date range. Must be a valid ISO 8601 datetime string.
</ParamField>

<ParamField query="groupBy" type="string" required>
  How to group the results. Valid values: `agent`, `feature`, `provider`, `model`, `day`, `week`, `month`.

  * **Entity grouping** (`agent`, `feature`, `provider`, `model`): groups by the corresponding field, sorted by total credits descending.
  * **Temporal grouping** (`day`, `week`, `month`): groups by time period using PostgreSQL `date_trunc`, sorted chronologically.
</ParamField>

#### Optional

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

<ParamField query="feature" type="string">
  Filter events by feature name before aggregating.
</ParamField>

<ParamField query="provider" type="string">
  Filter events by AI provider before aggregating.
</ParamField>

### Response

<ResponseField name="groupBy" type="string">
  The grouping criterion used (mirrors the request parameter).
</ResponseField>

<ResponseField name="startDate" type="string (ISO 8601)">
  Start of the queried date range.
</ResponseField>

<ResponseField name="endDate" type="string (ISO 8601)">
  End of the queried date range.
</ResponseField>

<ResponseField name="data" type="array">
  Aggregated results per group.

  <Expandable title="Summary item object" defaultOpen>
    <ResponseField name="groupKey" type="string">
      The value identifying this group. For entity grouping this is the entity ID or name (e.g. agent ID, feature name). For temporal grouping this is an ISO 8601 timestamp of the period start.
    </ResponseField>

    <ResponseField name="agentName" type="string">
      Name of the agent. Only present when `groupBy=agent`.
    </ResponseField>

    <ResponseField name="totalCreditsCharged" type="number">
      Sum of credits charged in this group.
    </ResponseField>

    <ResponseField name="totalInputTokens" type="integer">
      Sum of input tokens consumed in this group.
    </ResponseField>

    <ResponseField name="totalOutputTokens" type="integer">
      Sum of output tokens generated in this group.
    </ResponseField>

    <ResponseField name="eventCount" type="integer">
      Total number of consumption events in this group.
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

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

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request GET 'https://dashboard.laburen.com/api/consumption-events/summary?startDate=2025-01-01T00:00:00.000Z&endDate=2025-01-31T23:59:59.000Z&groupBy=agent' \
  --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',
    groupBy: 'agent',
  });

  const response = await fetch(`${apiUrl}/consumption-events/summary?${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/summary",
      headers={
          "Authorization": f"Bearer {api_key}",
      },
      params={
          "startDate": "2025-01-01T00:00:00.000Z",
          "endDate": "2025-01-31T23:59:59.000Z",
          "groupBy": "agent",
      },
  )

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

<ResponseExample>
  ```json Response theme={null}
  {
    "groupBy": "agent",
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-01-31T23:59:59.000Z",
    "data": [
      {
        "groupKey": "clxxxxxxxxxxxxxxxxx",
        "agentName": "Support Bot",
        "totalCreditsCharged": 12.450000,
        "totalInputTokens": 284500,
        "totalOutputTokens": 95200,
        "eventCount": 1523
      },
      {
        "groupKey": "clxxxxxxxxxxxxxxxxx",
        "agentName": "Sales Assistant",
        "totalCreditsCharged": 8.230000,
        "totalInputTokens": 195000,
        "totalOutputTokens": 67800,
        "eventCount": 987
      }
    ]
  }
  ```
</ResponseExample>