---
title: "Query Usage"
method: POST
path: "/wallets/usage/query"
tags: ["Wallets"]
---

# Query Usage

`POST /wallets/usage/query`

## Request

- Base URL: `/api` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/wallets/usage/query`
- Auth: API key in header `Authorization`

## Request body

- WalletUsageQueryRequest
  - `start` string, date-time, nullable
  - `end` string, date-time, nullable

## Response `200`

Successful Response

- WalletUsageResponse
  - `usage` WalletUsage, required
    - `start` string, date-time, required
    - `end` string, date-time, required
    - `truncated` boolean
    - `days` WalletUsageDay[]
      - `day` string, date, required
      - `category` string, required
      - `amount_musd` integer, required
      - `charge_count` integer, required
    - `sessions` WalletUsageSession[]
      - `session_id` string, nullable
      - `agent_id` string, uuid, nullable
      - `agent_name` string, nullable
      - `user_id` string, uuid, nullable
      - `user_email` string, nullable
      - `started_at` string, date-time, required
      - `last_at` string, date-time, required
      - `amount_musd` integer, required
      - `charge_count` integer, required
      - `charges` WalletUsageCharge[]
        - `created_at` string, date-time, required
        - `category` string, required
        - `resource_key` string, required
        - `model` string, nullable
        - `provider` string, nullable
        - `amount_musd` integer, required
        - `pricing_version` string, required
        - `measurement_id` string, nullable
        - `project_id` string, uuid, nullable
        - `input_tokens` integer, nullable
        - `output_tokens` integer, nullable
        - `cache_read_tokens` integer, nullable
        - `cache_write_tokens` integer, nullable
        - `request_count` integer, nullable
        - `sandbox_seconds` integer, nullable
        - `vcpu` integer, nullable
        - `memory_gib` integer, nullable
        - `action` string, nullable
        - `unit` string, nullable
        - `quantity` integer, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-06** `a9f9d2613767`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agenta-ai/apis/agenta-api/changes/wallets/usage/query/post.md)

---

[API](https://skmtc.dev/agenta-ai/apis/agenta-api.md) - [All operations](https://skmtc.dev/agenta-ai/apis/agenta-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agenta-ai/apis/agenta-api/revisions/ab601a2309da?raw)