---
type: api
title: Get agent consumption data
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-post-agent-builder-agents-agent-id-consumption
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-post-agent-builder-agents-agent-id-consumption
products:
  - Kibana
---

# Get agent consumption data

Availability:

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/agent_builder/agents/{agent_id}/consumption`
- `POST` `/s/{space_id}/api/agent_builder/agents/{agent_id}/consumption`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth)

#### Path Parameters

- `agent_id` (string)
  The unique identifier of the agent.

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Returns paginated, per-conversation token consumption data for a given agent. Includes input/output token counts, round counts, LLM call counts, and warnings for conversations with high token usage. Requires the manageAgents privilege. To learn more about monitoring agent token usage, refer to the [monitor usage documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/monitor-usage).<br/><br/>[Required authorization] Route required privileges: agentBuilder:manageAgents.

## Request Body

`application/json`

- `has_warnings` (boolean) — optional
  Filter to conversations with or without high-token warnings.
- `search` (string) — optional
  Free-text search filter on conversation title.
- `search_after` ([] object · max: 10000) — optional
  Cursor for pagination. Pass the search_after value from the previous response.
- `size` (number · min: 1 · max: 100 · default: 25) — optional
  Number of results per page.
- `sort_field` (enum  · default: updated_at) — optional
  Field to sort results by.
  Values: `updated_at`, `total_tokens`, `round_count`
- `sort_order` (enum  · default: desc) — optional
  Sort direction.
  Values: `asc`, `desc`
- `usernames` ([] string · max: 10000) — optional
  Filter results to conversations by these usernames.

## Response

Indicates a successful response

## Code Examples

#### Console

```console
POST kbn://api/agent_builder/agents/elastic-ai-agent/consumption
{"size": 25, "sort_field": "updated_at", "sort_order": "desc"}
```

#### curl

```curl
curl \
 -X POST "${KIBANA_URL}/api/agent_builder/agents/elastic-ai-agent/consumption" \
 -H "Authorization: ApiKey ${API_KEY}" \
 -H "Content-Type: application/json" \
 -H "elastic-api-version: 2023-10-31" \
 -d '{"size": 25, "sort_field": "updated_at", "sort_order": "desc"}'
```

## Response Examples

#### Consumption response

Example response with per-conversation token usage data

```json
{
  "aggregations": {
    "total_with_warnings": 0,
    "usernames": [
      "elastic",
      "admin"
    ]
  },
  "results": [
    {
      "conversation_id": "conv-abc123",
      "created_at": "2025-03-01T10:00:00Z",
      "llm_calls": 8,
      "round_count": 5,
      "title": "Help me search my data",
      "token_usage": {
        "input_tokens": 15000,
        "output_tokens": 3000,
        "total_tokens": 18000
      },
      "updated_at": "2025-03-01T10:15:00Z",
      "user": {
        "id": "uid-1",
        "username": "elastic"
      },
      "warnings": []
    },
    {
      "conversation_id": "conv-def456",
      "created_at": "2025-03-02T14:00:00Z",
      "llm_calls": 20,
      "round_count": 12,
      "title": "Analyze server logs",
      "token_usage": {
        "input_tokens": 250000,
        "output_tokens": 8000,
        "total_tokens": 258000
      },
      "updated_at": "2025-03-02T14:30:00Z",
      "user": {
        "id": "uid-2",
        "username": "admin"
      },
      "warnings": [
        {
          "input_tokens": 250000,
          "round_id": "round-7",
          "type": "high_input_tokens"
        }
      ]
    }
  ],
  "search_after": [
    1709391000000,
    "2025-03-02T14:30:00Z"
  ],
  "total": 2
}
```