---
title: "Aggregated wholesale usage for a date range"
method: GET
path: "/api/v1/partner/usage"
tags: ["Partners"]
---

# Aggregated wholesale usage for a date range

`GET /api/v1/partner/usage`

## Request

- Base URL: `https://www.agenttax.io`
- URL: `https://www.agenttax.io/api/v1/partner/usage`
- Auth: API key in header `X-API-Key`

Per-user call counts + wholesale cost for the given period. Used by partners to reconcile their monthly invoice.

Default period: current calendar month. `per_user` array is capped at 5000 rows ordered by cost descending — `pagination.truncated` flags when totals exceed that. Totals row is unaffected by truncation.

**Auth:** `ptx_live_…` provisioning key. **Rate limit:** 30/min per partner key.

## Query parameters

- `from` string, date-time: ISO date-time. Defaults to start of current calendar month (usage) / previous month (revshare).
- `to` string, date-time: ISO date-time. Must be after `from`. Exclusive upper bound.

## Response `200`

Aggregated usage and per-user breakdown.

- PartnerUsageResponse
  - `partner` object, required
    - `id` string, required
    - `slug` string, required
  - `period` object, required
    - `from` string, date-time, required
    - `to` string, date-time, required
  - `totals` object, required
    - `calls` integer, required
    - `free_tier_calls` integer, required
    - `billable_calls` integer, required
    - `wholesale_cost_usd` string, required: USD as a fixed-precision decimal string. Avoid float math in clients.
    - `total_users` integer, required
  - `per_user` object[], required
    - `external_id` string, required
    - `partner_user_id` string, required
    - `calls` integer, required
    - `free` integer, required
    - `billable` integer, required
    - `cost_usd` string, required: USD as a fixed-precision decimal string. Avoid float math in clients.
  - `pagination` object, required
    - `per_user_returned` integer, required
    - `per_user_cap` integer, required: Hard limit; defaults to 5000.
    - `truncated` boolean, required
    - `truncation_note` string, nullable, required

## Other responses

- `400`: Invalid date range (`to` must be after `from`).
- `401`: Invalid partner provisioning key.
- `429`: Rate limited.
- `503`: Database unavailable.

---

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