---
title: "Get Trace Events"
method: GET
path: "/v2/trace/{trace_id}/events"
tags: ["traces"]
---

# Get Trace Events

`GET /v2/trace/{trace_id}/events`

Projected, typed view of a trace's telemetry — drives the trace viewer.

## Path parameters

- `trace_id` string, uuid, required

## Query parameters

- `since_seq` integer — Return only events derived from spans with sequence > since_seq. Use -1 (default) for the first page, then pass the previous `next_seq` while `has_more` is true. Once caught up, use `latest_seq` for incremental polling.
- `limit` integer — Maximum completed span references to project in this page.

## Response `200`

Successful Response

- TraceEventsResponse
  - `events` union[], required
    - union
      - UserMessageEvent
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'user_message', required
        - `text` string, required
      - AgentMessageEvent
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'agent_message', required
        - `text` string, nullable
        - `reasoning` string, nullable
        - `tool_calls` AgentToolCall[]
          - `tool_call_id` string, nullable
          - `name` string, required
          - `arguments` object
          - `subagent_event_id` string, nullable
        - `finish_reason` string, nullable
        - `refusal` string, nullable
      - ToolCallEvent — A single MCP tool call with its result merged in. Mirrors what FastMCP returns: ``result_data`` preserves ``structuredContent`` when present; otherwise text content is unwrapped into ``result_text`` so renderers don't have to dig.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'tool_call', required
        - `method` string, required
        - `tool_call_id` string, nullable
        - `tool_name` string, nullable
        - `arguments` object
        - `result_text` string, nullable
        - `result_data` unknown
        - `error` string, nullable
        - `is_screenshot` boolean
        - `screenshot_url` string, nullable
      - ScenarioEvent — A task-lifecycle RPC (``tasks.start`` / ``tasks.grade``). Projected from the ``task``-sourced step the SDK harness records around the run. Kept under the legacy ``scenario_*`` kinds the viewer consumes.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'scenario_setup' | 'scenario_evaluate', required
        - `name` string, required
        - `arguments` object
        - `result` unknown
        - `error` string, nullable
      - SubagentEvent — A nested-agent invocation (one ``AgentTool.__call__``).
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'subagent', required
        - `agent_name` string, required
        - `arguments` object
        - `result` unknown
      - ObservationEvent — One robot observation tick (``step.observation`` under ``hud.robot.step.v1``): the numeric state the policy saw at ``tick`` (camera frames travel as ``VideoSegmentEvent`` streams). ``state`` maps each env-contract feature group -> its :class:`StateFeature` (per-dim names + values). Pairs with the :class:`InferenceEvent` at the same ``tick``.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'robot_observation', required
        - `tick` integer
        - `state` object
      - InferenceEvent — One robot inference (``step.inference`` under ``hud.robot.step.v1``). Carries the ``[T, A]`` action chunk the policy produced at a re-infer ``tick``. Emitted only on re-infer ticks (a chunk boundary), so it marks the decision points the viewer renders on its episode slider. ``tick`` matches the paired :class:`ObservationEvent`.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'robot_inference', required
        - `tick` integer
        - `chunk` array[]
          - number[]
        - `chunk_length` integer
        - `names` string[]
      - VideoSegmentEvent — One CMAF fragment of a camera's H.264 stream. Projected from ``step.video_segment`` under ``hud.robot.step.v1``: camera frames stream as video instead of a JPEG per tick. ``index`` orders the fragments per ``camera`` (``index`` 0 is the init segment); the viewer feeds the ordered ``url``s to one ``<video>`` via MSE. ``fps`` maps a control tick onto video time. ``url`` is the presigned S3 segment (``None`` only if offload/presign hasn't completed).
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'robot_video_segment', required
        - `camera` string
        - `index` integer
        - `fps` integer
        - `url` string, nullable
      - FileSnapshotEvent — A post-setup workspace manifest of paths + hashes captured before the agent starts. Emitted as ``filetracking.snapshot`` under ``hud.filetracking.v1``. Build source plus :class:`FileSetupEvent` patches derive this state; applying subsequent :class:`FileChangeEvent` patches reconstructs the agent timeline.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'file_snapshot', required
        - `files_scanned` integer
        - `truncated` boolean
        - `files` FileManifestEntry[]
          - `path` string, required
          - `size` integer
          - `content_hash` string, nullable
      - FileSetupEvent — Workspace changes made by scenario setup before the agent starts.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'file_setup', required
        - `files_scanned` integer
        - `files_changed` integer
        - `truncated` boolean
        - `patches` FilePatch[]
          - `path` string, required
          - `status` 'added' | 'modified' | 'deleted', required
          - `patch` string
          - `size_before` integer
          - `size_after` integer
          - `content_hash_before` string, nullable
          - `content_hash_after` string, nullable
      - FileChangeEvent — A workspace diff captured between steps. Projected from ``filetracking.diff`` under ``hud.filetracking.v1``: the files that changed since the previous scan. Interleaves with tool/agent events by ``seq``/time; correlate to the step timeline by ``started_at``. ``truncated`` marks a big diff capped over the per-scan budget (e.g. an ``npm install`` / ``git checkout``).
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'file_change', required
        - `files_scanned` integer
        - `files_changed` integer
        - `truncated` boolean
        - `patches` FilePatch[]
          - `path` string, required
          - `status` 'added' | 'modified' | 'deleted', required
          - `patch` string
          - `size_before` integer
          - `size_after` integer
          - `content_hash_before` string, nullable
          - `content_hash_after` string, nullable
      - FileCaptureEvent — Final changed-file artifacts captured from ``filetracking.capture``.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'file_capture', required
        - `files_scanned` integer
        - `files_changed` integer
        - `files_eligible` integer
        - `files_captured` integer
        - `files_skipped` integer
        - `truncated` boolean
        - `files` CapturedFile[]
          - `path` string, required
          - `status` 'added' | 'modified', required
          - `size` integer, required
          - `content_hash` string, nullable
          - `content_type` string
          - `url` string, nullable
          - `download_url` string, nullable
      - RawEvent — Fallback for spans we don't know how to project. Covers new SDK categories and custom user @instrument calls. Kept so the viewer can still display *something* without dropping data.
        - `id` string, required
        - `parent_id` string, nullable
        - `started_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `seq` integer
        - `kind` 'raw', required
        - `category` string, required
        - `name` string, required
        - `attributes` object
  - `latest_seq` integer, required
  - `next_seq` integer, required
  - `has_more` boolean, required
  - `status` string, required
  - `reward` number, nullable

## Other responses

- `400` — Invalid or malformed request
- `401` — Missing or invalid credentials
- `403` — Caller may not access this resource
- `404` — Referenced entity does not exist
- `409` — Resource already exists
- `422` — Validation Error

---

[API](https://skmtc.dev/hud/apis/hud-platform.md) · [All operations](https://skmtc.dev/hud/apis/hud-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hud/hud-platform/revisions/58558fc733d9/schema)