---
title: "List box events"
method: GET
path: "/boxes/{boxId}/events"
tags: ["Box"]
---

# List box events

`GET /boxes/{boxId}/events`

Return Box work, lifecycle, and progress events so product UIs can show what the box is doing. Event payloads are extensible. Clients can long-poll this endpoint with `sort=asc` and a cursor to stream responses. Response events expose agent text, streaming partials via `data.is_streaming`, and tool calls/results via `data.tools`.

## Path parameters

- `boxId` string, required

## Query parameters

- `limit` integer
- `cursor` string, nullable
- `sort` 'asc' | 'desc'
- `type` string

## Response `200`

Box work and lifecycle events.

- EventsResponse
  - `ok` boolean, required
  - `type` 'events.list', required — Stable success envelope discriminator added by v1.
  - `id` string, required
  - `events` BoxEvent[], required — Box work and lifecycle event objects. Event shapes are intentionally extensible; branch on each event `type` when present.
    - `id` string
    - `type` string, required
    - `timestamp` integer
    - `taskId` string, nullable
    - `data` object
  - `pageInfo` PageInfo
    - `nextCursor` string, nullable, required
    - `hasMore` boolean, required
    - `limit` integer, required

## Other responses

- `401` — Missing or invalid bearer token.
- `402` — Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API.
- `404` — Resource not found.

---

[API](https://skmtc.dev/ascii/apis/box-public-api-v1.md) · [All operations](https://skmtc.dev/ascii/apis/box-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ascii/box-public-api-v1/revisions/82d576f82046/schema)