---
title: Get Usage Report
description: 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.
docs_index: /docs/llms.txt
lastUpdated: 2026-10-23
product: v0 API
type: reference
prerequisites:
  - /docs/api/v1/quickstart
---

> For an index of all documentation, see [/docs/llms.txt](/docs/llms.txt).

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.

#### `GET /v1/reports/usage`

## Rate limit

This endpoint allows 60 requests per minute per user or team scope. Requests over the limit return a `429 Too Many Requests` response.

## Usage

```typescript
import { v0 } from 'v0-sdk'

const result = await v0.reports.getUsage()

console.log(result)
```

```bash
curl -X GET https://api.v0.dev/v1/reports/usage   -H "Authorization: Bearer $V0_API_KEY"   -H "Content-Type: application/json"
```

## API Signature

### Request

#### Query Parameters

- `startDate?: string` Query parameter "startDate"
- `endDate?: string` Query parameter "endDate"
- `chatId?: string` Query parameter "chatId"
- `messageId?: string` Query parameter "messageId"
- `userId?: string` Query parameter "userId"
- `limit?: number` Query parameter "limit"
- `cursor?: string` Base64 encoded cursor containing pagination data

### Response

- `object: 'list'`
- `data: object[]`
  - `item: object`
    - `id: string`
    - `object: 'usage_event'`
    - `type?: 'image_generation' | 'message' | 'manual_debit' | 'api_request' | 'inline-edit' | 'buy-template' | 'reverse_template_sale' | 'refund_template_purchase'`
    - `promptCost?: string`
    - `completionCost?: string`
    - `totalCost: string`
    - `chatId?: string`
    - `messageId?: string`
    - `userId?: string` Deprecated - use user object instead
    - `user?: object`
    - `createdAt: string` The ISO timestamp representing when the usage event was created.
- `pagination: object`
  - `hasMore: boolean`
  - `nextCursor?: string`
  - `nextUrl?: string`
- `meta: object`
  - `totalCount: number`

---

For a semantic overview of all documentation, see [/docs/sitemap.md](/docs/sitemap.md)

For an index of all available documentation, see [/docs/llms.txt](/docs/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/docs/agents.md](/docs/agents.md)