# GET /trace

> Talos 0.7 · Since 0.6

The body is the frozen `Vec<FrameDelta>`.

What the delta budget left out is reported in `x-argus-trace-truncated`, and the page's span in `x-argus-trace-range`, so a client can page backwards with `?before=` without the body shape changing.

## Request

#### Query parameters

| Parameter | Shape | Meaning |
|---|---|---|
| `frames` | integer | how many frames to return, newest last. Default **60**, maximum 300. |
| `before` | integer | only frames strictly older than this, for paging backwards |

## Response

#### Response: array of `FrameDelta`

What changed on one frame.

| Field | Type | Present | Description |
|---|---|---|---|
| `frame` | `integer` | always | The frame this delta describes. |
| `keyframe` | `boolean` | always | True when `transforms` lists every non-static entity rather than only the dirty ones. True exactly when `frame % 60 == 0`. |
| `transforms` | `TransformDelta[]` | always | Entities whose transform changed this frame (every entity on a keyframe). |
| `events` | `EventRecord[]` | always | Events that fired on this frame, in order. |

#### Response: `EventRecord`

One frame-stamped thing that happened.

| Field | Type | Present | Description |
|---|---|---|---|
| `seq` | `integer` | always | Monotonic per-process sequence number. Strictly increasing, no gaps. |
| `frame` | `integer` | always | The frame the event fired on. |
| `time` | `number` | always | Simulated seconds since the scene loaded. |
| `kind` | `EventKind` | always | What happened. |

#### Response: `EventKind`

The payload of an `EventRecord`, tagged by `type` on the wire.

| Value | Meaning |
|---|---|
| `collision` | Two colliders started or stopped touching. Mirrors `argus_host::GameEvent::Collision`. |
| `trigger` | A sensor volume was entered or left. Mirrors `argus_host::GameEvent::Trigger`. |
| `custom` | `ctx.events.emit(name, data)` from a behavior, or `ctx.events.emitTo(to, name, data)`. |
| `script_error` | A behavior threw, ran away or blew its per-tick budget and was disabled — or, with `disabled` false, keeps running: it threw a stale handle (`entity-despawned`) from a per-tick hook, or its `update` stayed over its wall-clock budget (phase `budget`) under the host's default `OverrunPolicy::Warn`. |
| `script_warning` | A behavior did something the engine let pass but its author almost certainly did not mean. The behavior keeps running; nothing is disabled. |
| `ui` | The game UI's stack, focus or an activation changed. |
| `log` | `ctx.log(...)` from a behavior. |

#### Response: `TransformDelta`

One entity's transform at one frame.

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `string` | always | The entity's stable scene id. |
| `position` | `number[3]` | always | World-space position, `[x, y, z]`. |
| `rotation` | `number[4]` | sometimes | World-space rotation as a quaternion, `[x, y, z, w]`. Present when it changed since this entity's last delta, and on every keyframe. |
| `scale` | `number[3]` | sometimes | Local scale, present only on the frames it changed, and on every keyframe. |

## Example

```sh
curl "http://127.0.0.1:7700/trace"
```

Start a server with `argus run --serve`; the port is `--port` (7700 by default). The request and response fields are in the query API guide.