---
title: "Get Usage Report"
method: GET
path: "/reports/usage"
tags: ["reports"]
---

# Get Usage Report

`GET /reports/usage`

Retrieves detailed usage events for the authenticated user or team, including costs, event types, models used, and metadata. Shows the same data as displayed in the usage dashboard. Can be filtered by chatId to show usage for a specific chat, or by userId to show usage for a specific user.

## Query parameters

- `startDate` string, date-time
- `endDate` string, date-time
- `chatId` string
- `messageId` string
- `userId` string
- `limit` number
- `cursor` string — Base64 encoded cursor containing pagination data

## Response `200`

Success

- object
  - `object` 'list', required
  - `data` object[], required
    - `id` string, required
    - `object` 'usage_event', required
    - `type` 'image_generation' | 'message' | 'manual_debit' | 'api_request' | 'inline-edit' | 'buy-template' | 'reverse_template_sale' | 'refund_template_purchase'
    - `promptCost` string
    - `completionCost` string
    - `totalCost` string, required
    - `chatId` string
    - `messageId` string
    - `userId` string — Deprecated - use user object instead
    - `user` UserSummarySchema — Details of the authenticated user, including profile and contact information.
      - `id` string, required — A unique identifier for the user.
      - `object` 'user', required — Fixed value identifying this object as a user.
      - `name` string — Optional full name of the user.
      - `email` string, required — The user's email address.
      - `avatar` string, required — URL to the user's avatar image.
      - `createdAt` string, date-time, required — The ISO timestamp representing when the user was created.
      - `updatedAt` string, date-time — The ISO timestamp of the last update to the user.
    - `createdAt` string, date-time, required — The ISO timestamp representing when the usage event was created.
  - `pagination` object, required
    - `hasMore` boolean, required
    - `nextCursor` string
    - `nextUrl` string
  - `meta` object, required
    - `totalCount` number, required — Number of events in this response

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `413` — Payload Too Large
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-01-20** `86302d0793b1` — 3 warning
  - added the new `buy-template` enum value to the `data/items/type` response property for the response status `200`
  - added the new `refund_template_purchase` enum value to the `data/items/type` response property for the response status `200`
  - added the new `reverse_template_sale` enum value to the `data/items/type` response property for the response status `200`
- **2025-11-12** `5941dc463f60` — 2 info
  - added the new optional `query` request parameter `userId`
  - added the required property `data/items/createdAt` to the response with the `200` status
- **2025-10-23** `bcf554284606` — 2 breaking, 1 info
  - added the pattern `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` to the `query` request parameter `endDate`
  - added the pattern `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` to the `query` request parameter `startDate`
  - added the optional property `data/items/user` to the response with the `200` status
- **2025-09-23** `901cfbcf3419` — 1 info
  - endpoint added
- …earlier changes not shown

[Full history](https://skmtc.dev/vercel/apis/v0-platform-api-beta/changes/reports/usage/get.md)

---

[API](https://skmtc.dev/vercel/apis/v0-platform-api-beta.md) · [All operations](https://skmtc.dev/vercel/apis/v0-platform-api-beta/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vercel/v0-platform-api-beta/revisions/79811cd54faa/schema)