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

# Get agent consumption data

Authentication: required

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

- `space_id` (string) — optional
  An identifier for the space. If `space_id` is not provided in the URL, the default space is used. Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- `agent_id` (string) — required
  The unique identifier of the agent.

## Description

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`

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

`application/json`

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