Implementation:Cohere ai Cohere python UsageBilledUnits Model

Knowledge Sources	Cohere Python SDK
Domains	SDK, Billing, Usage Tracking, Pydantic Models
Last Updated	2026-02-15 14:00 GMT

Overview

Pydantic model that tracks billable usage units across different Cohere API operations including input tokens, output tokens, search units, and classifications.

Description

UsageBilledUnits captures the billing breakdown for a single API call. It contains four optional float fields: input_tokens (number of billed input tokens), output_tokens (number of billed output tokens), search_units (number of billed search units, applicable to RAG and rerank operations), and classifications (number of billed classification units). All fields default to None since not every API operation incurs all unit types. This model is typically nested within ApiMeta under the billed_units field and is present in response objects such as V2ChatResponse, EmbedResponse, and RerankResponse. The class extends UncheckedBaseModel with extra="allow" for forward compatibility with new billing unit types.

Usage

Use UsageBilledUnits to inspect and track the cost of API calls. After receiving any Cohere API response, access response.meta.billed_units to retrieve the billing breakdown. This is useful for cost monitoring, usage dashboards, budget enforcement, and logging in production systems.

Code Reference

Source Location

• Repository: Cohere Python SDK
• File: src/cohere/types/usage_billed_units.py Lines L1-37

Signature

class UsageBilledUnits(UncheckedBaseModel):
    input_tokens: typing.Optional[float] = pydantic.Field(default=None)
    output_tokens: typing.Optional[float] = pydantic.Field(default=None)
    search_units: typing.Optional[float] = pydantic.Field(default=None)
    classifications: typing.Optional[float] = pydantic.Field(default=None)

Import

from cohere.types import UsageBilledUnits

I/O Contract

Fields

Field	Type	Required	Default	Description
input_tokens	Optional[float]	No	None	The number of billed input tokens.
output_tokens	Optional[float]	No	None	The number of billed output tokens.
search_units	Optional[float]	No	None	The number of billed search units.
classifications	Optional[float]	No	None	The number of billed classification units.

Configuration

Setting	Value	Description
extra	"allow"	Permits additional fields not defined in the schema, ensuring forward compatibility with new billing unit types.
smart_union	True	Pydantic V1 only: enables smart union type resolution.

Usage Examples

import cohere

client = cohere.ClientV2(api_key="your-api-key")

# Chat usage tracking
response = client.chat(
    model="command-a-03-2025",
    messages=[{"role": "user", "content": "Explain quantum computing in one sentence."}],
)

billed = response.meta.billed_units
print(f"Input tokens:  {billed.input_tokens}")
print(f"Output tokens: {billed.output_tokens}")
print(f"Search units:  {billed.search_units}")
print(f"Classifications: {billed.classifications}")

# Aggregate usage across multiple calls
total_input = 0.0
total_output = 0.0
for prompt in prompts:
    resp = client.chat(model="command-a-03-2025", messages=[{"role": "user", "content": prompt}])
    if resp.meta and resp.meta.billed_units:
        total_input += resp.meta.billed_units.input_tokens or 0.0
        total_output += resp.meta.billed_units.output_tokens or 0.0

print(f"Total billed: {total_input} input, {total_output} output tokens")

Related Pages

• Implementation:Cohere_ai_Cohere_python_V2ChatResponse_Model -- Chat response model containing meta.billed_units
• Implementation:Cohere_ai_Cohere_python_EmbedResponse_Model -- Embed response model containing meta.billed_units
• Implementation:Cohere_ai_Cohere_python_RerankResponse_Model -- Rerank response model containing meta.billed_units
• Environment:Cohere_ai_Cohere_python_Python_SDK_Runtime