Get agent consumption data Experimental; 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. To learn more about monitoring agent token usage, refer to the monitor usage documentation.

[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 
{
  "has_warnings": true,
  "size": 10,
  "sort_field": "total_tokens",
  "sort_order": "desc",
  "usernames": [
    "elastic",
    "admin"
  ]
}
Response examples (200)
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
}