Get agent consumption data

Base URL: https://{kibana_url}

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

Auth

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.

Required authorization

Privileges agentBuilder:manageAgents

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 for more information.
agent_id string required: The unique identifier of the agent.

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

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

Response

200

Indicates a successful response

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Get consumption data for an agent with default pagination

Console Kibana Dev Tools

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

curl Shell

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

Example response with per-conversation token usage data

{
  "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
}

Request Console 1 / 2 languages

Get consumption data filtered by username with warnings

Console Kibana Dev Tools

POST kbn:/api/agent_builder/agents/AGENT_ID/consumption
{
  "has_warnings": true,
  "size": 10,
  "sort_field": "total_tokens",
  "sort_order": "desc",
  "usernames": [
    "elastic",
    "admin"
  ]
}

Generated from the API spec

curl Shell

curl \
 -X POST "${KIBANA_URL}/api/agent_builder/agents/${AGENT_ID}/consumption" \
 -H "Authorization: ApiKey ${API_KEY}" \
 -H "Content-Type: application/json" \
 -H "elastic-api-version: 2023-10-31" \
 -d '{
    "has_warnings": true,
    "size": 10,
    "sort_field": "total_tokens",
    "sort_order": "desc",
    "usernames": [
      "elastic",
      "admin"
    ]
  }'

Generated from the API spec

Response

Example response with per-conversation token usage data

{
  "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
}