---
title: "Get Chat Task Steps"
method: GET
path: "/v1/chat/tasks/{task_id}/steps"
tags: ["sdk-v1"]
---

# Get Chat Task Steps

`GET /v1/chat/tasks/{task_id}/steps`

Return the public-timeline steps for a task.

Pulls all :class:`TraceEvent` rows for the task in DB order, then
collapses them via :func:`map_trace_events_to_public_steps` into
the 4 stable public step types: ``thinking``, ``tool_call``,
``agent_delegation``, ``message``.

The internal trace event taxonomy has ~32 ``event_type`` strings
today; SDK callers see only the 4 types listed above. Internal
events not on the public allow-list (LLM calls, memory ops,
visualization ticks, DAG bookkeeping) are silently dropped --
intentionally, so internal trace evolution doesn't break the SDK
contract.

Args:
    task_id: Path parameter; the target task's primary key.
    authed: ``(Agent, AgentApiKey)`` tuple resolved by the auth
        dependency. The agent here is the key-bound agent.
    db: SQLAlchemy session.

Returns:
    :class:`StepsResponse` with ``task_id``, ``agent_id``, and the
    steps array in ``started_at`` ascending order. In-flight steps
    appear with ``status='running'`` and ``completed_at=null`` so
    SDK clients can poll this endpoint and observe progress.

Raises:
    V1ApiError 401: missing / invalid / revoked key.
    V1ApiError 404: task missing or not owned by the calling agent.

## Path parameters

- `task_id` integer, required

## Response `200`

Successful Response

- StepsResponse — ``GET /v1/chat/tasks/{task_id}/steps`` response body. Steps are returned in monotonic ``started_at`` order. The endpoint is a polling primitive: each call returns the full known history so far (including any still-running steps as ``status='running'``) so SDK clients can resume after a network blip without state.
  - `task_id` integer, required — The task these steps belong to.
  - `agent_id` integer, required — The task's agent.
  - `steps` PublicStep[] — Public-timeline steps in started_at ascending order.
    - `id` string, required — Stable identifier for this step within the task. Includes a type prefix (e.g. 'tool_call:abc123') so SDK clients can dedupe across re-polls.
    - `type` 'thinking' | 'tool_call' | 'agent_delegation' | 'message', required — One of: thinking, tool_call, agent_delegation, message. Other internal event types are not surfaced on this endpoint.
    - `status` 'running' | 'completed' | 'failed', required — running while the corresponding end event has not yet fired (i.e. the SDK polled mid-step), completed on a normal end event, failed when the end event carries success=false.
    - `started_at` string, date-time, required — UTC timestamp of the start event for this step.
    - `completed_at` string, date-time, nullable — UTC timestamp of the end event. Null while status is 'running'.
    - `data` object — Type-specific payload. See class docstring for the keys expected per step type.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/xorbitsai/apis/xagent.md) · [All operations](https://skmtc.net/xorbitsai/apis/xagent/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xorbitsai/xagent/revisions/33e4ba4936ad/schema)