# pydantic\_ai.usage ### UsageBase #### Attributes ##### input\_tokens Number of input/prompt tokens. **Type:** [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\[[`int`](https://docs.python.org/3/library/functions.html#int), `Field`(`validation_alias`\=(`AliasChoices`(`input_tokens`, `request_tokens`)))\] **Default:** `0` ##### cache\_write\_tokens Number of tokens written to the cache. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### cache\_read\_tokens Number of tokens read from the cache. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### output\_tokens Number of output/completion tokens. **Type:** [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\[[`int`](https://docs.python.org/3/library/functions.html#int), `Field`(`validation_alias`\=(`AliasChoices`(`output_tokens`, `response_tokens`)))\] **Default:** `0` ##### input\_audio\_tokens Number of audio input tokens. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### cache\_audio\_read\_tokens Number of audio tokens read from the cache. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### output\_audio\_tokens Number of audio output tokens. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### details Any extra details returned by the model. **Type:** [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\[[`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`int`](https://docs.python.org/3/library/functions.html#int)\], `BeforeValidator`([`lambda`](https://docs.python.org/3/glossary.html#term-lambda) `d`: `d` [`or`](https://docs.python.org/3/reference/expressions.html#or) {})\] **Default:** `dataclasses.field(default_factory=(dict[str, int]))` ##### total\_tokens Sum of `input_tokens + output_tokens`. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) #### Methods ##### \_\_copy\_\_ ```python def __copy__() -> UsageBase ``` Shallow copy that also copies mutable fields like `details`. ###### Returns `UsageBase` ##### opentelemetry\_attributes ```python def opentelemetry_attributes() -> dict[str, int] ``` Get the token usage values as OpenTelemetry attributes. ###### Returns [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`int`](https://docs.python.org/3/library/functions.html#int)\] ##### has\_values ```python def has_values() -> bool ``` Whether any values are set and non-zero. ###### Returns [`bool`](https://docs.python.org/3/library/functions.html#bool) ### RequestUsage **Bases:** `UsageBase` LLM usage associated with a single request. This is an implementation of `genai_prices.types.AbstractUsage` so it can be used to calculate the price of the request using [genai-prices](https://github.com/pydantic/genai-prices). #### Methods ##### incr ```python def incr(incr_usage: RequestUsage) -> None ``` Increment the usage in place. ###### Returns [`None`](https://docs.python.org/3/library/constants.html#None) ###### Parameters **`incr_usage`** : [`RequestUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RequestUsage) The usage to increment by. ##### \_\_add\_\_ ```python def __add__(other: RequestUsage) -> RequestUsage ``` Add two RequestUsages together. This is provided so it's trivial to sum usage information from multiple parts of a response. **WARNING:** this CANNOT be used to sum multiple requests without breaking some pricing calculations. ###### Returns [`RequestUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RequestUsage) ##### extract `@classmethod` ```python def extract( cls, data: Any, provider: str, provider_url: str, provider_fallback: str, api_flavor: str = 'default', details: dict[str, Any] | None = None, ) -> RequestUsage ``` Extract usage information from the response data using genai-prices. ###### Returns [`RequestUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RequestUsage) ###### Parameters **`data`** : [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) The response data from the model API. **`provider`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str) The actual provider ID **`provider_url`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str) The provider base\_url **`provider_fallback`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str) The fallback provider ID to use if the actual provider is not found in genai-prices. For example, an OpenAI model should set this to "openai" in case it has an obscure provider ID. **`api_flavor`** : [`str`](https://docs.python.org/3/library/stdtypes.html#str) _Default:_ `'default'` The API flavor to use when extracting usage information, e.g. 'chat' or 'responses' for OpenAI. **`details`** : [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `None` Becomes the `details` field on the returned `RequestUsage` for convenience. ### RunUsage **Bases:** `UsageBase` LLM usage associated with an agent run. Responsibility for calculating request usage is on the model; Pydantic AI simply sums the usage information across requests. #### Attributes ##### requests Number of requests made to the LLM API. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### tool\_calls Number of successful tool calls executed during the run. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### input\_tokens Total number of input/prompt tokens. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### cache\_write\_tokens Total number of tokens written to the cache. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### cache\_read\_tokens Total number of tokens read from the cache. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### input\_audio\_tokens Total number of audio input tokens. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### cache\_audio\_read\_tokens Total number of audio tokens read from the cache. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### output\_tokens Total number of output/completion tokens. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `0` ##### details Any extra details returned by the model. **Type:** [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`int`](https://docs.python.org/3/library/functions.html#int)\] **Default:** `dataclasses.field(default_factory=(dict[str, int]))` #### Methods ##### incr ```python def incr(incr_usage: RunUsage | RequestUsage) -> None ``` Increment the usage in place. ###### Returns [`None`](https://docs.python.org/3/library/constants.html#None) ###### Parameters **`incr_usage`** : [`RunUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RunUsage) | [`RequestUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RequestUsage) The usage to increment by. ##### \_\_add\_\_ ```python def __add__(other: RunUsage | RequestUsage) -> RunUsage ``` Add two RunUsages together. This is provided so it's trivial to sum usage information from multiple runs. ###### Returns [`RunUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RunUsage) ### Usage **Bases:** [`RunUsage`](/docs/ai/api/pydantic-ai/usage/#pydantic_ai.usage.RunUsage) Deprecated alias for `RunUsage`. ### UsageLimits Limits on model usage. The request count is tracked by pydantic\_ai, and the request limit is checked before each request to the model. Token counts are provided in responses from the model, and the token limits are checked after each response. Each of the limits can be set to `None` to disable that limit. #### Attributes ##### request\_limit The maximum number of requests allowed to the model. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `request_limit` ##### tool\_calls\_limit The maximum number of successful tool calls allowed to be executed. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `tool_calls_limit` ##### input\_tokens\_limit The maximum number of input/prompt tokens allowed. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `input_tokens_limit if input_tokens_limit is not None else request_tokens_limit` ##### output\_tokens\_limit The maximum number of output/response tokens allowed. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `output_tokens_limit if output_tokens_limit is not None else response_tokens_limit` ##### total\_tokens\_limit The maximum number of tokens allowed in requests and responses combined. **Type:** [`int`](https://docs.python.org/3/library/functions.html#int) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `total_tokens_limit` ##### count\_tokens\_before\_request If True, perform a token counting pass before sending the request to the model, to enforce `input_tokens_limit` ahead of time. This may incur additional overhead (from calling the model's `count_tokens` API before making the actual request) and is disabled by default. Supported by: - Anthropic - Google - Bedrock Converse - OpenAI Responses **Type:** [`bool`](https://docs.python.org/3/library/functions.html#bool) **Default:** `count_tokens_before_request` #### Methods ##### has\_token\_limits ```python def has_token_limits() -> bool ``` Returns `True` if this instance places any limits on token counts. If this returns `False`, the `check_tokens` method will never raise an error. This is useful because if we have token limits, we need to check them after receiving each streamed message. If there are no limits, we can skip that processing in the streaming response iterator. ###### Returns [`bool`](https://docs.python.org/3/library/functions.html#bool) ##### check\_before\_request ```python def check_before_request(usage: RunUsage) -> None ``` Raises a `UsageLimitExceeded` exception if the next request would exceed any of the limits. ###### Returns [`None`](https://docs.python.org/3/library/constants.html#None) ##### check\_tokens ```python def check_tokens(usage: RunUsage) -> None ``` Raises a `UsageLimitExceeded` exception if the usage exceeds any of the token limits. ###### Returns [`None`](https://docs.python.org/3/library/constants.html#None) ##### check\_before\_tool\_call ```python def check_before_tool_call(projected_usage: RunUsage) -> None ``` Raises a `UsageLimitExceeded` exception if the next tool call(s) would exceed the tool call limit. ###### Returns [`None`](https://docs.python.org/3/library/constants.html#None)