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

# Get agent consumption data

Availability: Experimental since 9.4

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

## Paths

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

#### Path parameters

- `agent_id` (string) — required
  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).

## Required authorization

- Privileges: `agentBuilder:manageAgents`

## Authentication

- Api key: `Authorization: <value>`
  These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`
- Basic: `Authorization: Basic <credentials>`

## Header parameters

- `kbn-xsrf` (string) — required
  A required header to protect against CSRF attacks

## 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 items: 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 items: 10000) — optional
  Filter results to conversations by these usernames.

## Response

Indicates a successful response

`application/json`

## 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
}
```