# GET /v1/tasks/{task_id}/trace

> Every step: tools called with a summary of inputs and outputs, timings, tokens and cost per turn.

In [Work API](https://vestra.ai/developers/reference/api/work.md): The work Bash does on its computer: list it, read it, stop it or delete it.

Send `Authorization: Bearer vk_test_...` on every call.

Every step: tools called with a summary of inputs and outputs, timings, tokens and cost per turn.

Your API key, scope `runtime` or `all`. On the card: [`events`](https://vestra.ai/developers/events.md). Every call here is a checked sample.

## Request

Path:

- `task_id` (`string`, required): The piece of work's id (`task_...`).

## Answers 200

- `object` (`"task_trace"`): Always task_trace.
- `task_id` (`string`): The task (task_...).
- `steps` (`object[]`): Every tool Bash used, in order.
  - `tool_use_id` (`string`): The step: one use of a tool.
  - `name` (`string | null`): The tool Bash used; null when it was not recorded.
  - `input_summary` (`string | null`): What Bash did with it, in a line: never the raw input. Null when there is none.
  - `output_summary` (`string | null`): What came back, in a line; null when there is none.
  - `is_error` (`boolean`): Whether the step failed.
  - `started_at` (`string`): When it started, as an ISO 8601 time.
  - `finished_at` (`string | null`): When it finished, as an ISO 8601 time; null while running.
  - `duration_ms` (`number | null`): How long it took, in milliseconds; null while running.
- `turns` (`object[]`): Every call to the model, in order, with its tokens and cost.
  - `turn_id` (`string`): The model turn: one call to the model.
  - `model` (`string | null`): The model that answered; null when it was not recorded.
  - `input_tokens` (`number`): Tokens the model read.
  - `output_tokens` (`number`): Tokens the model wrote.
  - `cache_read_tokens` (`number`): Of the tokens it read, how many came from the cache, at a lower price.
  - `cost_usd` (`number`): What this turn cost, in billed US dollars.
  - `duration_ms` (`number | null`): How long it took, in milliseconds; null when not recorded.
  - `status` (`string | null`): How it ended, as recorded; null when not recorded.
  - `started_at` (`string`): When it started, as an ISO 8601 time.
- `totals` (`object`): The turns added up.
  - `input_tokens` (`number`): All tokens read.
  - `output_tokens` (`number`): All tokens written.
  - `cost_usd` (`number`): What every turn cost together, in billed US dollars.

## Code

**TypeScript**

```ts
const trace = await vestra.events.trace('task_91d');
```

**Python**

```python
trace = vestra.events.trace("task_91d")
```

**CLI**

```bash
vestra events task_91d
```

**HTTP**

```bash
# Stream a conversation live. If the connection drops, reconnect with the last seq you saw.
curl -N "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/events" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Last-Event-ID: 41"

# Read the same events as JSON. You get them in pages, after the seq you give.
curl "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/events?format=json&after=41" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Read a task afterwards. You get every step of one task, with tokens and cost per turn.
curl "$VESTRA_BASE_URL/v1/tasks/task_91d/trace" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Send events to your server. Register a URL and the events it wants. The signing secret is shown only once.
curl "$VESTRA_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/vestra", "events": ["task.completed", "interaction.created", "usage.cap_reached"] }'

# Catch up on what you missed. List the events your webhooks were sent, newest first.
curl "$VESTRA_BASE_URL/v1/events?type=task.failed" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "events",
    "arguments": { "user": "traveller-42", "conversation": "conv_8f2k", "after": 0 }
  }
}
```