---
title: "List Usage Events"
method: GET
path: "/usage/events"
tags: ["Usage"]
---

# List Usage Events

`GET /usage/events`

Lists individual credit usage events. Each event includes the credits charged and, when available, associated token counts.

## Query parameters

- `start` string, date-time — Inclusive ISO 8601 start timestamp. Defaults to seven days ago.
- `end` string, date-time — Exclusive ISO 8601 end timestamp. Defaults to the current time.
- `userId` string — Filter usage by user. Team owners and billing members may select any team member; other callers may select only themselves.
- `chatId` string — Filter usage by chat identifier.
- `messageId` string — Filter usage by message identifier.
- `limit` integer — Maximum billing records considered per credit source (1-100, default 50). Related records may be combined into one event.
- `cursor` string — Opaque cursor returned by the previous page. It preserves the prior range and filters, so other query parameters may be omitted on subsequent pages.

## Response `200`

Response for status 200

- UsageEventList
  - `object` 'list', required — Object type identifier.
  - `range` object, required — Time range covered by the response.
    - `start` string, date-time, required — Inclusive ISO 8601 start timestamp.
    - `end` string, date-time, required — Exclusive ISO 8601 end timestamp.
  - `scope` object, required — Authorized billing scope used for this response.
    - `id` string, required — Billing scope identifier.
    - `type` 'team' | 'personal', required — Billing scope type.
    - `isTeamWide` boolean, required — Whether the response includes usage for the entire team.
    - `userId` string — User attribution applied to the response, when filtered.
  - `data` object[], required — Usage events in this page.
    - `id` string, required — Billing event identifier.
    - `object` 'usage_event', required — Object type identifier.
    - `type` string, required — Kind of product usage represented by the event.
    - `createdAt` string, date-time, required — Timestamp of the usage event.
    - `userId` string — Attributed user identifier.
    - `chatId` string — Related chat identifier.
    - `messageId` string — Related message identifier.
    - `model` string — Model associated with the event.
    - `sources` string[], required — Credit sources used by the event.
    - `waived` boolean, required — Whether credits fully waived this event.
    - `tokens` object, nullable, required — Persisted token counts, or null when the source message is unavailable.
      - `input` number, required — Input amount excluding cached input.
      - `output` number, required — Output amount.
      - `cacheRead` number, required — Cache-read input amount.
      - `cacheWrite` number, required — Cache-write input amount.
      - `total` number, required — Total amount across all categories.
    - `creditsCost` object, required
      - `input` number, required — Input amount excluding cached input.
      - `output` number, required — Output amount.
      - `cacheRead` number, required — Cache-read input amount.
      - `cacheWrite` number, required — Cache-write input amount.
      - `total` number, required — Total amount across all categories.
      - `charged` number, required — Credits charged after a full waiver.
  - `pagination` object, required — Pagination state for this response.
    - `hasMore` boolean, required — Whether another page is available.
    - `cursor` string, nullable, required — Cursor for the next page, or null at the end.

## Other responses

- `401` — Response for status 401
- `403` — Response for status 403
- `409` — Response for status 409
- `422` — Response for status 422
- `500` — Response for status 500

---

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