| navigation_title | Monitor usage and costs | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| description | Understand how Agent Builder calculates token usage, monitor conversation costs, and learn how execution-based billing works on Elastic Cloud Serverless. | |||||||||||||||
| applies_to |
|
|||||||||||||||
| products |
|
This page covers how to monitor token usage in {{agent-builder}} and understand how usage translates to costs across different deployment types.
For observability beyond token counts, {{agent-builder}} can also collect detailed execution traces into your {{es}} deployment. To turn on trace collection and explore or alert on the data, refer to Collect agent traces.
When working with {{agent-builder}}, total token usage typically exceeds the visible conversation text. Because {{agent-builder}} uses an agentic framework, a single user request often triggers multiple model calls to process reasoning steps, run tools, and interpret results.
{applies_to}stack: ga 9.5+ To keep this efficient, {{agent-builder}} automatically routes some of these low-effort operations to a faster, lower-cost model. For details, see Fast model routing.
Token counts include:
- Input tokens: These are tokens sent to the model, which accumulate throughout the session. They include the user's current query, the conversation history from previous rounds, system prompts, and the results returned from any tools used during execution.
- Output tokens: These are tokens generated by the model. These include the final response visible to the user, as well as all internal reasoning steps, tool calls, and intermediate results generated by the model.
:::{note} Each conversation round includes all previous rounds as context. This means token usage at each step depends on the entire conversation size, not only the current message. :::
For more information on billing and token costs, refer to Elastic pricing.
stack: preview =9.4
To retrieve per-conversation token usage data for a specific agent across users, use the token consumption API. For quick examples, refer to Token consumption.
This API complements the UI by returning token totals, round counts, LLM call counts, and warning indicators without exposing message content or tool results.
:::{note} This API provides visibility into token usage but does not support setting token limits or quotas for users or agents. :::
At the end of each round, the total token usage is displayed after the agent response. Input tokens are represented by {icon}sort_up, and output tokens by {icon}sort_down:
:::{image} images/token-usage.png :screenshot: :width: 800px :alt: Screenshot of the token usage display, showing input and output token counts :::
To view the raw JSON response which includes detailed token information, click the View JSON button. This opens a modal with the complete, raw response data:
:::{image} images/token-usage-json-raw-response.png :screenshot: :width: 900px :alt: Screenshot of the JSON raw response modal :::
How {{agent-builder}} usage is billed depends on your deployment type.
On {{serverless-full}}, {{agent-builder}} usage is billed based on executions. An execution is measured by each completed interaction with an AI agent (a chat input and output). More complex interactions, measured by the number of input tokens used, are metered for additional executions. Each unit of 50,000 input tokens counts as one additional execution. If the agent encounters an error and does not return a response, no executions are metered.
Every {{serverless-short}} project includes a free monthly allocation of agent executions, and volume tier discounts apply at higher usage levels. If your usage stays within the free allocation, there is no impact to your bill.
Example: In the following conversation round, the agent used 91,613 input tokens. This results in 2 {{agent-builder}} executions (1 base execution + 1 additional execution for the second block of 50,000 input tokens).
:::{image} images/execution-billing-example.png :screenshot: :width: 800px :alt: Agent Builder conversation round showing 91,613 input tokens and 4,096 output tokens beneath the agent response, which maps to 2 billed executions :::
When an agent triggers a workflow as part of its response, the workflow execution is metered separately. Each {{serverless-short}} project also includes a free monthly allocation of workflow executions.
For detailed rates, free allocations, and tier breakpoints, refer to the billing dimensions page for your solution:
- {{es-serverless}} billing dimensions
- {{obs-serverless}} billing dimensions
- {{elastic-sec}} {{serverless-short}} billing dimensions
For general pricing information, refer to Elastic pricing.
{{agent-builder}} and Workflows on {{ech}} are currently under promotional pricing and available at no additional charge.
{{agent-builder}} and Workflows on self-managed deployments are currently under promotional pricing and available at no additional charge. {{agent-builder}} is included with the Enterprise license tier.