UsageMetadata Class — langchain Architecture

Source Code

libs/core/langchain_core/messages/ai.py lines 104–157

class UsageMetadata(TypedDict):
    """Usage metadata for a message, such as token counts.

    This is a standard representation of token usage that is consistent across models.

    Example:
        ```python
        {
            "input_tokens": 350,
            "output_tokens": 240,
            "total_tokens": 590,
            "input_token_details": {
                "audio": 10,
                "cache_creation": 200,
                "cache_read": 100,
            },
            "output_token_details": {
                "audio": 10,
                "reasoning": 200,
            },
        }
        ```

    !!! warning "Behavior changed in `langchain-core` 0.3.9"

        Added `input_token_details` and `output_token_details`.

    !!! note "LangSmith SDK"

        The LangSmith SDK also has a `UsageMetadata` class. While the two share fields,
        LangSmith's `UsageMetadata` has additional fields to capture cost information
        used by the LangSmith platform.
    """

    input_tokens: int
    """Count of input (or prompt) tokens. Sum of all input token types."""

    output_tokens: int
    """Count of output (or completion) tokens. Sum of all output token types."""

    total_tokens: int
    """Total token count. Sum of `input_tokens` + `output_tokens`."""

    input_token_details: NotRequired[InputTokenDetails]
    """Breakdown of input token counts.

    Does *not* need to sum to full input token count. Does *not* need to have all keys.
    """

    output_token_details: NotRequired[OutputTokenDetails]
    """Breakdown of output token counts.

    Does *not* need to sum to full output token count. Does *not* need to have all keys.
    """