---
title: "Get run timeline"
method: GET
path: "/agent/runs/{runId}/timeline"
tags: ["agent"]
---

# Get run timeline

`GET /agent/runs/{runId}/timeline`

Retrieve chronological setup and lifecycle timeline events for an agent run.

## Path parameters

- `runId` string, required

## Response `200`

Run timeline events

- GetRunTimelineResponse — Response body for listing run timeline events.
  - `events` AIRunTimelineEvent[], required
    - `event_uuid` string, required — Unique client- or server-generated identifier for this event.
    - `run_id` string, required — Run that owns this event.
    - `execution_id` integer — Run execution associated with this event, when available.
    - `event_type` 'oz_run_created' | 'oz_run_claimed' | 'worker_container_ready' | 'shared_session_started' | 'agent_started' | 'oz_run_done' | 'oz_run_blocked' | 'oz_run_cancelled' | 'oz_run_failed' | 'oz_run_errored' | 'vm_shutdown', required — Type of timeline event recorded for a run.
    - `occurred_at` string, date-time, required — Timestamp when the event occurred.
    - `payload` object — Optional event-specific JSON payload.

## Other responses

- `400` — Missing run ID
- `401` — Authentication required
- `403` — No permission to access run
- `500` — Internal server error

## Changes

- **2026-08-15** `a0daf9e59774` — 6 warning, 10 info
  - added the new `oz_run_blocked` enum value to the `events/items/event_type` response property for the response status `200`
  - added the new `oz_run_cancelled` enum value to the `events/items/event_type` response property for the response status `200`
  - added the new `oz_run_done` enum value to the `events/items/event_type` response property for the response status `200`
  - added the new `oz_run_errored` enum value to the `events/items/event_type` response property for the response status `200`
  - …12 more

[Change history](https://skmtc.dev/warp/apis/oz-agent-api/changes/agent/runs/:runId/timeline/get.md)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/warp/oz-agent-api/revisions/a0daf9e59774/schema)