---
title: "Get Agent Usage Summary"
method: GET
path: "/api/agents/{agent_id}/usage/summary"
tags: ["agent-usage"]
---

# Get Agent Usage Summary

`GET /api/agents/{agent_id}/usage/summary`

## Request

- Base URL: `https://api.tintin-x.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tintin-x.com/api/agents/{agent_id}/usage/summary`
- Auth: HTTP bearer

Summary for one agent: totals, action-type bars, model bars, top 5 sessions.

When `conversation_id` is set, the same shape is returned but every
aggregation is restricted to that conversation and `top_sessions` is
empty. Cached 10 minutes (per (user_id, agent_id, days, conversation_id)).

## Path parameters

- `agent_id` string, uuid, required

## Query parameters

- `days` integer
- `conversation_id` string, uuid, nullable: Restrict the summary to one conversation. Skips the top-sessions block (it would only contain that one row).

## Response `200`

Successful Response

- AgentUsageSummaryResponse
  - `agent_id` string, uuid, required
  - `days` integer, required
  - `conversation_id` string, nullable
  - `total_credits_cents` integer, required
  - `total_actually_charged_cents` integer
  - `has_whitelisted_rows` boolean
  - `total_calls` integer, required
  - `by_action_type` UsageBucketRow[], required
    - `label` string, required
    - `credits_cents` integer, required
    - `calls` integer, required
  - `by_model` UsageBucketRow[], required
    - `label` string, required
    - `credits_cents` integer, required
    - `calls` integer, required
  - `top_sessions` SessionUsageRow[], required
    - `conversation_id` string, nullable, required
    - `title` string, nullable, required
    - `credits_cents` integer, required
    - `calls` integer, required
    - `last_activity_at` string, date-time, nullable, required
  - `generated_at` string, date-time, required
  - `cache_hit` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tintin-x/apis/tintin-api.md) · [All operations](https://skmtc.dev/tintin-x/apis/tintin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tintin-x/apis/tintin-api/revisions/8839a8d0a66c?raw)