Usage Limits and Cost Tracking

Every result carries its own usage stats

result.usage, a property, not a method, is a RunUsage with request count, input tokens, and output tokens for that run.

result = agent.run_sync("Say hi.")
print(result.usage)
# RunUsage(requests=1, input_tokens=4, output_tokens=2, ...)

This is the same information LangSmith traces show you per run in the LangSmith course, just available locally on every result, no tracing backend required to see it.

Capping usage before it happens

UsageLimits lets you cap a run before it runs away: a maximum number of model requests, useful for agentic loops that could keep calling tools forever, or a maximum token count, useful for cost control.

from dotenv import load_dotenv
from pydantic_ai import Agent, UsageLimits
from pydantic_ai.exceptions import UsageLimitExceeded

load_dotenv()

agent = Agent("google:gemini-3.5-flash-lite")


def main() -> None:
    result = agent.run_sync("Say hi in one word.")
    print("Output:", result.output)
    print("Usage:", result.usage)

    print("\nSetting an unreasonably low token limit on purpose:")
    try:
        agent.run_sync(
            "Say hi in one word.",
            usage_limits=UsageLimits(total_tokens_limit=1),
        )
    except UsageLimitExceeded as error:
        print("Caught UsageLimitExceeded:", error)

If a run would exceed the limit, Pydantic AI raises UsageLimitExceeded instead of quietly letting the bill grow. This is a real safety mechanism, not just an observability nicety: an agent stuck in a tool-calling loop against a limit you didn't set could otherwise burn through your Gemini quota with no natural stopping point.

Limits compose with delegation

Because Lesson 12's delegated calls pass usage=ctx.usage through, a usage_limits= set on the outer run's run_sync call caps the combined total across every delegated agent call too, not just the top-level agent. One limit protects the whole call tree.