Get agent consumption data Technical Preview; added in 9.4.0

POST /api/agent_builder/agents/{agent_id}/consumption
Api key auth Basic auth

Spaces method and path for this operation:

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

Refer to 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.

[Required authorization] Route required privileges: agentBuilder:manageAgents.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • agent_id string Required

    The unique identifier of the agent.

application/json

Body

  • has_warnings boolean

    Filter to conversations with or without high-token warnings.

  • search string

    Free-text search filter on conversation title.

  • search_after array

    Cursor for pagination. Pass the search_after value from the previous response.

    Not more than 10000 elements.

  • size number

    Number of results per page.

    Minimum value is 1, maximum value is 100. Default value is 25.

  • sort_field string

    Field to sort results by.

    Values are updated_at, total_tokens, or round_count. Default value is updated_at.

  • sort_order string

    Sort direction.

    Values are asc or desc. Default value is desc.

  • usernames array[string]

    Filter results to conversations by these usernames.

    Not more than 10000 elements.

Responses

  • 200 application/json

    Indicates a successful response

POST /api/agent_builder/agents/{agent_id}/consumption 
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"}'

POST kbn://api/agent_builder/agents/elastic-ai-agent/consumption
{"size": 25, "sort_field": "updated_at", "sort_order": "desc"}
Request examples
Get consumption data for an agent with default pagination 
{
  "size": 25,
  "sort_field": "updated_at",
  "sort_order": "desc"
}
Get consumption data filtered by username with warnings 
{
  "size": 10,
  "usernames": [
    "elastic",
    "admin"
  ],
  "sort_field": "total_tokens",
  "sort_order": "desc",
  "has_warnings": true
}
Response examples (200)
Example response with per-conversation token usage data 
{
  "total": 2,
  "results": [
    {
      "user": {
        "id": "uid-1",
        "username": "elastic"
      },
      "title": "Help me search my data",
      "warnings": [],
      "llm_calls": 8,
      "created_at": "2025-03-01T10:00:00Z",
      "updated_at": "2025-03-01T10:15:00Z",
      "round_count": 5,
      "token_usage": {
        "input_tokens": 15000,
        "total_tokens": 18000,
        "output_tokens": 3000
      },
      "conversation_id": "conv-abc123"
    },
    {
      "user": {
        "id": "uid-2",
        "username": "admin"
      },
      "title": "Analyze server logs",
      "warnings": [
        {
          "type": "high_input_tokens",
          "round_id": "round-7",
          "input_tokens": 250000
        }
      ],
      "llm_calls": 20,
      "created_at": "2025-03-02T14:00:00Z",
      "updated_at": "2025-03-02T14:30:00Z",
      "round_count": 12,
      "token_usage": {
        "input_tokens": 250000,
        "total_tokens": 258000,
        "output_tokens": 8000
      },
      "conversation_id": "conv-def456"
    }
  ],
  "aggregations": {
    "usernames": [
      "elastic",
      "admin"
    ],
    "total_with_warnings": 0
  },
  "search_after": [
    1709391000000,
    "2025-03-02T14:30:00Z"
  ]
}