Query endpoints
All read endpoints take x-api-key and the shared parameters. Reads are
scoped to the project resolved from the key. Below are the most-used endpoints, grouped by need; see
the overview for auth and parameter units.
Sessions & scenes
Section titled “Sessions & scenes”| Method | Path | Purpose | Extra params |
|---|---|---|---|
GET |
/api/v1/sessions |
Recent sessions (id, visitor, event count, start/end). | limit, cameraMode |
GET |
/api/v1/sessions/:id/meta |
Coarse session descriptor (device/scene/user). | — |
GET |
/api/v1/sessions/:id/trajectory |
One session’s ordered walked path. | scene, limit |
GET |
/api/v1/scenes |
Distinct scenes with activity (for the scene picker). | limit |
Heatmaps
Section titled “Heatmaps”| Method | Path | Purpose | Extra params |
|---|---|---|---|
GET |
/api/v1/heatmaps/pointer |
2D pointer heatmap bins. | bins, scene, source, session, cameraMode |
GET |
/api/v1/heatmaps/world |
3D world-space pointer heatmap. Omit cellSize to auto-size from scene/region bounds (ADR 0040). |
cellSize, region, scene, source, cameraMode |
GET |
/api/v1/heatmaps/world/stats |
World-heatmap totals: { cellSize, cells, hits } — true occupied-cell + hit counts behind the truncated voxel list (ADR 0040). |
cellSize, region, scene, source, cameraMode |
GET |
/api/v1/heatmaps/gaze |
3D world-space gaze heatmap (requires capture.gaze). |
cellSize, region, scene, session, cameraMode |
GET |
/api/v1/heatmaps/gaze/stats |
Gaze-heatmap totals: { cellSize, cells, hits } (ADR 0040). |
cellSize, region, scene, session, cameraMode |
GET |
/api/v1/heatmaps/perf |
3D spatial FPS heatmap (#145): frame_perf binned by camera position → vx,vy,vz,samples,avg_fps,min_fps, ordered avg_fps ASC. |
cellSize, region, scene, session, cameraMode |
GET |
/api/v1/heatmaps/camera |
View-direction heatmap (spherical bins). | bins, scene, session, cameraMode |
GET |
/api/v1/coverage/view-histogram |
360° view-coverage histogram (#146): sessions bucketed by how much of the object they saw (bucket, sessions). Same dome grid as /heatmaps/camera; buckets are 25%-wide bands (0/25/50/75). Powers the dashboard “View coverage” panel. |
bins, scene, session, cameraMode |
GET |
/api/v1/heatmaps/position |
Top-down floor-plan camera-position heatmap. | cellSize, region, scene, session, cameraMode |
GET |
/api/v1/heatmaps/click-rays |
Click rays per voxel/mesh. Flat pointers reconstruct the ray origin on the camera near plane (ADR 0043). | cellSize, scene, source, session |
GET |
/api/v1/heatmaps/errors |
Spatial error heatmap (#154): voxel-binned position of positioned runtime_error + graphics_diagnostic events — where things break. Same row shape as /heatmaps/world. |
cellSize, region, scene, session, severity, category, errorKind |
GET |
/api/v1/heatmaps/boundary |
Guardian / boundary-touch heatmap (#157, ADR 0048): voxel-binned position of xr_boundary_proximity events — where room-scale VR visitors reach their play-space boundary. The boundary polygon is never transmitted (on-device only). Same row shape as /heatmaps/world. |
cellSize, region, scene, session |
GET |
/api/v1/heatmaps/boundary/stats |
Boundary-heatmap totals: { cellSize, cells, hits } — the boundary sibling of /heatmaps/world/stats (ADR 0040). |
cellSize, region, scene, session |
GET |
/api/v1/heatmaps/flow |
Gaze→mesh flow links. Position-aware mode (groupByOrigin/originVoxel) bins by click-time camera standpoint — best for walkable scenes. |
bins, limit, scene, session, cellSize, groupByOrigin, originVoxel, cameraMode |
| Method | Path | Purpose | Extra params |
| —— | —————————— | ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– | ——————————————————————————————— |
GET |
/api/v1/heatmaps/pointer |
2D pointer heatmap bins. | bins, scene, source, session, cameraMode |
GET |
/api/v1/heatmaps/mesh-uv |
Per-mesh texture-space (UV) heatmap (#149): interaction uv coordinates on one mesh binned over its own UV space. Same {gx,gy,count} rows as /heatmaps/pointer. |
mesh (required), bins, scene, source, session |
GET |
/api/v1/heatmaps/world |
3D world-space pointer heatmap. Omit cellSize to auto-size from scene/region bounds (ADR 0040). |
cellSize, region, scene, source, cameraMode |
GET |
/api/v1/heatmaps/world/stats |
World-heatmap totals: { cellSize, cells, hits } — true occupied-cell + hit counts behind the truncated voxel list (ADR 0040). |
cellSize, region, scene, source, cameraMode |
GET |
/api/v1/heatmaps/gaze |
3D world-space gaze heatmap (requires capture.gaze). |
cellSize, region, scene, session, cameraMode |
GET |
/api/v1/heatmaps/gaze/stats |
Gaze-heatmap totals: { cellSize, cells, hits } (ADR 0040). |
cellSize, region, scene, session, cameraMode |
GET |
/api/v1/heatmaps/camera |
View-direction heatmap (spherical bins). | bins, scene, session, cameraMode |
GET |
/api/v1/heatmaps/position |
Top-down floor-plan camera-position heatmap. | cellSize, region, scene, session, cameraMode |
GET |
/api/v1/heatmaps/click-rays |
Click rays per voxel/mesh. Flat pointers reconstruct the ray origin on the camera near plane (ADR 0043). | cellSize, scene, source, session |
GET |
/api/v1/heatmaps/flow |
Gaze→mesh flow links. Position-aware mode (groupByOrigin/originVoxel) bins by click-time camera standpoint — best for walkable scenes. |
bins, limit, scene, session, cellSize, groupByOrigin, originVoxel, cameraMode |
For large scenes (ADR 0040): leave cellSize off and the collector derives a
sensible voxel size from the scene’s registered world bounds — or from a
region=minX,minY,minZ,maxX,maxY,maxZ box when you pass one to drill in. The
/stats siblings report the real occupied-cell and hit totals behind the
truncated top-N voxels so cold spots and coverage stay honest. The dashboard’s 3D
world heatmap normalizes to the 95th-percentile cell so a couple of hotspots no
longer wash out the rest.
Meshes & interactions
Section titled “Meshes & interactions”| Method | Path | Purpose | Extra params |
|---|---|---|---|
GET |
/api/v1/meshes/top |
Most-interacted meshes. | limit, session |
GET |
/api/v1/meshes/sources |
Part-popularity source split: per (mesh, source) count, scoped to active interactions (gaze excluded) (#74). |
limit, scene, source, session |
GET |
/api/v1/meshes/trend |
Part-popularity trend: per (mesh, bucket) count for sparklines, active interactions only (#74). |
interval, limit, scene, source, session |
GET |
/api/v1/meshes/dwell |
Object dwell ranking from mesh_visibility. |
scene, session |
GET |
/api/v1/meshes/blind-spots |
Blind spots (#143): meshes with high mesh_visibility time but little mesh_interaction + hover_dwell engagement — rendered but never noticed. |
limit, scene, session |
GET |
/api/v1/meshes/reachability |
Per-mesh interaction-distance histogram: how far each mesh sat from the click-time camera standpoint (#151). | bucketSize, limit, scene, source, session |
GET |
/api/v1/hover/dwell |
Hover-hesitation ranking from hover_dwell. |
limit, scene, source, session |
GET |
/api/v1/clicks/dead |
Dead-click rate (clicks that hit empty space). | scene, source, session |
GET |
/api/v1/clicks/rage |
Rage-click clusters. | interval, minRepeats, limit, scene, source, session |
GET |
/api/v1/interactions/sources |
Input-source breakdown (mouse/touch/XR/hand/gaze/…). | limit, scene, source, session |
GET |
/api/v1/input-actions/top |
Most-used app-level shortcuts from input_action (#75). |
limit, scene, source, session |
Performance
Section titled “Performance”| Method | Path | Purpose | Extra params |
|---|---|---|---|
GET |
/api/v1/perf |
Rendering-performance summary (samples, avg/min/p50 FPS). | session |
GET |
/api/v1/perf/by-device |
Per-session median FPS by device class + UA-derived browser/OS. | scene, session |
GET |
/api/v1/perf/resources |
GPU/memory footprint summary from resource_sample. |
session |
GET |
/api/v1/perf/compile-stalls |
Shader/pipeline compile stalls. | limit, scene, session |
GET |
/api/v1/perf/churn |
Perf-correlated churn (#144): share of ended sessions that ended shortly after an FPS dip / compile stall, split by cause. Derived from existing events, no schema change. | windowMs, fpsThreshold, stallMs, scene, session |
GET |
/api/v1/capabilities |
Capability fallbacks/recoveries (e.g. WebGPU→WebGL2). | limit, scene, session |
GET |
/api/v1/graphics-diagnostics |
Opt-in GPU-health incidents from graphics_diagnostic: per (severity, category, backend) count, folding markers + rollups (ADR 0021). Empty unless captureGraphicsDiagnostics is enabled. |
scene, session |
GET |
/api/v1/rendering-technology |
Always-on rendering-technology mix from session_start.graphics: per (api, backend, api_version, shading_language) session count (ADR 0021). Powers the dashboard “Rendering technology” panel. |
scene, session |
Navigation & XR
Section titled “Navigation & XR”| Method | Path | Purpose | Extra params |
|---|---|---|---|
GET |
/api/v1/camera-gestures |
Camera-navigation breakdown (orbit/pan/dolly/zoom/…). | limit, scene, source, session |
GET |
/api/v1/coverage |
Scene coverage / dead zones from camera positions. | cellSize, scene, source, session |
GET |
/api/v1/camera/distance |
Camera distance / zoom histogram. | centerX/Y/Z, bucketSize, scene, source, session |
GET |
/api/v1/navigation |
Per-session travel (segments, distance, active vs idle). | moveThreshold, scene, source, session |
GET |
/api/v1/backtrack |
Path-retrace / backtracking ratio: per-scene leaderboard of how often visitors re-walk a coarse grid cell (scene, sessions, entries, revisits, backtrack_ratio). |
cellSize, limit, scene, session |
GET |
/api/v1/xr/rotation |
XR head/view rotation rate (motion-sickness proxy). | rapidTurn, limit, scene, session |
GET |
/api/v1/xr/sources |
XR input-source usage (hand vs controller vs gaze). | limit, scene, session |
GET |
/api/v1/xr/abandonment |
XR session abandonment. | limit, scene, session |
GET |
/api/v1/xr/locomotion |
XR locomotion & comfort: per-session fly/navigate/teleport mix + span. | limit, scene, session |
GET |
/api/v1/xr/boundary-contacts |
Guardian boundary contacts (#157, ADR 0048): per XR session contacts (near-boundary approaches) + near_ms (time in the near zone) — a room-scale comfort signal. On-device outcome only; no room geometry. |
limit, scene, session |
GET |
/api/v1/xr/tracking |
XR tracking quality: per-session degraded/lost-tracking time (hand vs controller) + span. | limit, scene, session |
GET |
/api/v1/ar/placement/time-to-place |
AR placement time-to-place histogram (#156): bucket (ms lower edge), placements. |
bucketMs (default 2000), scene, session |
GET |
/api/v1/ar/placement/attempts |
AR re-placement distribution (#156): attempts, placements. |
scene, session |
GET |
/api/v1/ar/placement/surfaces |
AR surface breakdown (#156): surface (floor/wall/table/ceiling/unknown), placements, avg_scale. |
scene, session |
Time & volume
Section titled “Time & volume”| Method | Path | Purpose | Extra params |
|---|---|---|---|
GET |
/api/v1/timeseries |
Event-volume buckets over time (bucket, events, avg_fps). |
scene, interval, type |
GET |
/api/v1/event-counts |
Per-event-type counts over the range. | scene |
GET |
/api/v1/funnel |
Ordered, per-session conversion funnel (#78): sessions reaching each step (step, sessions). Steps are caller-supplied; the OSS dashboard has no authoring UI (ADR 0038). |
steps (JSON, required), scene, cameraMode |
GET |
/api/v1/scene-retention |
Canned scene/level retention funnel (#147): session counts flowing scene → scene in observed order (from_scene, to_scene, sessions), from scene_change markers — no steps to author. |
limit |
GET |
/api/v1/load-bounce |
Load → bounce/abandon funnel (#152): sessions bucketed by initial asset_load time band, with the count that bounced — no pointer_* / mesh_interaction / camera_gesture after load — per band (band, sessions, bounced). Derived; no schema change. |
bands (ascending ms CSV, optional), scene |
GET |
/api/v1/variant-leaderboard |
Variant → conversion leaderboard (#150): custom events grouped by their name (a configurator variant), ranked by views, with sessions, conversions, and avg_dwell_ms. Optional conversion predicate adds the per-variant conversion rate. |
variant (JSON), conversion (JSON), limit, scene, cameraMode, session |
Replay (raw events)
Section titled “Replay (raw events)”| Method | Path | Purpose | Extra params |
|---|---|---|---|
GET |
/api/v1/sessions/:id/events |
Ordered raw event stream for replay. | — |
Example
Section titled “Example”curl -H "x-api-key: $KEY" \ "https://collect.example.com/api/v1/perf?session=<session-id>"