# GET /perf

> Talos next · Since 0.6

## Response

#### Response: `PerfSample`

One frame's cost, as the agent sees it.

| Field | Type | Present | Description |
|---|---|---|---|
| `presentation` | `PresentationSample` | sometimes |  |
| `frame` | `integer` | always | The frame these numbers describe. |
| `frame_ms` | `number` | always | Legacy host frame cost; the app reports simulation-step cost here, not presentation cadence. |
| `physics_ms` | `number` | always | Time inside the physics step. |
| `script_ms` | `number` | always | Time inside behavior `update` and event dispatch. |
| `render_ms` | `number` | always | Time inside render submission. |
| `p95_frame_ms` | `number` | always | 95th percentile of `frame_ms` over the last 120 frames. |
| `draw_calls` | `integer` | always | Draw calls submitted for the last frame, every pass counted. |
| `instances` | `integer` | always | Instances submitted in the opaque pass. |
| `triangles` | `integer` | always | Triangles submitted in the opaque pass. |
| `heap_mb` | `number` | always | Resident heap in mebibytes, or `0` when the host does not measure it. |
| `entities` | `integer` | always | Live entities. |
| `bodies` | `integer` | always | Rigid bodies in the physics world. |
| `agents` | `integer` | always | Crowd agents on the navmesh. |
| `time_scale` | `number` | always | Simulation time scale in effect (0 while paused). |
| `paused` | `boolean` | always | Whether the simulation is paused. |
| `nonfinite_scrubbed` | `integer` | always | Non-finite floats scrubbed on the way out since process start. Non-zero means some subsystem produced a NaN or an infinity; see `crates/query/src/finite.rs`. |
| `unwired` | `UnwiredCalls` | always | Behavior calls the engine recorded but could not act on, cumulative since load. See `UnwiredCalls`; all-zero is healthy and is what an empty scene reports. |
| `ui_ms` | `number` | sometimes | Wall time of the game UI's tick and draw-list mapping, in milliseconds. 0 with no UI. `GET /ui/stats` breaks it down by screen. |
| `ui_draw_calls` | `integer` | sometimes | Draw calls the UI pass issued last frame (quad rounds plus text rounds). Part of `draw_calls`; 0 headless. |
| `terrain_load` | `TerrainLoadTimes` | sometimes | The scene load's terrain time by stage; all-zero with no terrain. |

#### Response: `PresentationSample`

| Field | Type | Present | Description |
|---|---|---|---|
| `presented_frames` | `integer` | always |  |
| `skipped_frames` | `integer` | always |  |
| `samples` | `integer` | always |  |
| `fps` | `number` | always |  |
| `mean_interval_ms` | `number` | always |  |
| `p95_interval_ms` | `number` | always |  |
| `cpu_work_ms` | `number` | always |  |
| `present_wait_ms` | `number` | always |  |
| `physics_ms` | `number` | always |  |
| `script_ms` | `number` | always |  |
| `render_submit_ms` | `number` | always |  |
| `render_width` | `integer` | always |  |
| `render_height` | `integer` | always |  |
| `window_width` | `integer` | always |  |
| `window_height` | `integer` | always |  |
| `vsync` | `boolean` | always |  |

#### Response: `TerrainLoadTimes`

Where the scene load's terrain time went, by stage, in milliseconds of each stage's own wall time.

| Field | Type | Present | Description |
|---|---|---|---|
| `prewarm_ms` | `number` | sometimes | Starting the renderer's terrain pipeline early (a read of the layers' material files). |
| `decode_ms` | `number` | sometimes | Reading and parsing the terrain file, and (drawn) decoding the layers' textures. |
| `cache_read_ms` | `number` | sometimes | Reading and decompressing the project's terrain cache, hits and misses alike. |
| `evaluate_ms` | `number` | sometimes | The evaluation apart from its cache reads (the stack's images and sculpt tiles, and the cells the cache did not have), plus bringing the ground to the roads, the water data and the collision query. |
| `mesh_ms` | `number` | sometimes | Building the cells' render meshes on the CPU (every level). |
| `upload_ms` | `number` | sometimes | Handing the layers, the cells' maps and the meshes to the renderer (GPU uploads). |
| `collider_ms` | `number` | sometimes | The cell entities, their colliders and the ground's material lookup. |
| `total_ms` | `number` | sometimes | The terrain attach's work, start to end, counting work a load made for it on another thread ahead of the attach in place of the attach's wait for it. |
| `disk_hits` | `integer` | sometimes | Cell results read back from the cache on disk: `0` on a cold load. |
| `cells_evaluated` | `integer` | sometimes | Cell results computed during the load: `0` on a warm one. |

#### Response: `UnwiredCalls`

Calls a behavior made that the engine recorded but could not act on.

| Field | Type | Present | Description |
|---|---|---|---|
| `audio_play` | `integer` | always | `ctx.audio.play` for an asset with no registered sound. |
| `particles_emit` | `integer` | always | `ctx.particles.emit` with a preset name outside the eight the contract defines. |
| `hud_set` | `integer` | always | `ctx.hud.set` for a field nothing draws. |
| `nav_speed_override` | `integer` | always | `ctx.nav.goTo(target, speed)` with a speed: the crowd has no per-agent speed setter. |
| `audio_bus` | `integer` | always | `ctx.audio.play({ bus })` or `ctx.audio.bus(name)` naming a bus `meta.audio` does not declare. The cue still plays, on the default bus. |
| `audio_snapshot` | `integer` | always | `ctx.audio.snapshot(name)` with no such snapshot in `meta.audio.snapshots`. |
| `audio_music` | `integer` | always | `ctx.audio.music.play(layer)` with no such layer in `meta.audio.music.layers`. |
| `body_push` | `integer` | sometimes | A `ctx.body` force, torque or impulse on a body that is not dynamic (kinematic or static), or through a handle whose body has gone. Nothing moved. |
| `joint_ignored` | `integer` | sometimes | A `ctx.joint` `setMotor`, `stopMotor` or `setLimits` on a fixed joint, or through a handle whose joint has gone. Nothing changed. |
| `vehicle_ignored` | `integer` | sometimes | A `ctx.vehicle.drive` on a vehicle the engine drives from the input actions (`input: "auto"`), or a `ctx.vehicle` call through a handle whose vehicle has gone. Nothing changed. |

## Example

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

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.