Session Queries
Session queries provide access to user engagement data, device analytics, and behavioral metrics for specific scenes in your XR applications.
Tips
- Compare across scenes: Run session queries for multiple scenes to identify which content resonates most
- Separate VR from WebGL: If you ship both headset and browser builds, filter by
runtime_hostso browser sessions don't skew headset metrics — see Filtering by device or platform - Scope a time window: Use
start_date/end_datefor a specific period, ordays_backfor a rolling one - Follow-up queries: After viewing sessions, try "What objectives are configured for this project?" to understand success metrics
Get scene sessions
Returns session data for a specific scene, including device breakdowns, duration statistics, and engagement analytics. This tool helps you understand how users are interacting with your XR content.
Sample queries for scene sessions
- "Show me sessions for scene X in project Y."
- "What devices are users using in my training scene?"
- "Get the last 30 days of sessions for the lobby scene."
- "How many sessions has my demo scene had?"
- "What's the average session duration for project 123?"
Response for scene sessions includes
- Total session count
- Session duration statistics (average, min, max)
- Device type breakdown (Quest, Vive, etc.)
- Temporal distribution of sessions
- User engagement indicators
Understanding the scene sessions response
The session response includes several key metrics:
- Session Count: Total number of completed sessions
- Device Analytics: Which hardware platforms users are using
- Duration Metrics: How long users spend in the experience
- Time Distribution: When sessions occur (useful for identifying peak usage)
For how Cognitive3D classifies session devices into canonical categories and families, see Device classification fields.
Parameters for scene sessions
| Parameter | Required | Description |
|---|---|---|
project_id |
Yes | The numeric project ID |
scene_id |
Yes | The scene ID (obtained from project details) |
version_id |
Yes | The version ID (obtained from project details) |
days_back |
No | Days of history to include (default: 90, max: 1000) |
start_date |
No | Start of the window — Unix milliseconds or ISO 8601 |
end_date |
No | End of the window — Unix milliseconds or ISO 8601 |
device_category |
No | Filter by hardware type — see Filtering by device or platform |
runtime_host |
No | Filter by how the app runs — see Filtering by device or platform |
limit |
No | Sessions per page (default: 1000, max: 1000) |
page |
No | 0-indexed page number (default: 0) |
Finding IDs
You can obtain scene_id and version_id from the get_project_details tool response.
Each of start_date and end_date overrides that end of the window; days_back
fills in whichever you leave out. So end_date on its own with days_back: 30
gives the 30 days before today, not the 30 days before end_date — supply both
dates when you want an exact historical range.
Very large scenes cap out server-side
A scene with enough sessions will eventually hit a server-side limit on both the reported total and how far you can page. The response tells you when that's happened and how to proceed — narrow the query with a date range or a device filter rather than paging further.
Filtering by device or platform
Sessions carry a canonical device classification, and you can filter on two independent parts of it. This is the way to separate VR headset usage from browser-based (WebGL) usage — for example, to stop low-frame-rate WebGL sessions from dragging down a performance average.
| Filter | What it describes |
|---|---|
device_category |
what the hardware is — a headset, glasses, phone, tablet, desktop, etc. |
runtime_host |
how the app reaches that hardware — native, browser, editor, etc. |
Each is a closed set — see Device classification fields
for the full vocabulary and how it's produced. Each filter accepts a single value
or a list, where a list means "any of these". The two are independent and
combine, so a WebGL session on a Windows PC is desktop + web_browser, while a
headset tethered to a PC is hmd + native_tethered.
These same two filters are available on the device-distribution and score tools, not just scene sessions.
Separating VR from WebGL
Use runtime_host for this, not device_category. Whether an experience is
running in a browser is a fact about the runtime, not about the hardware — and
in practice runtime_host is the more dependable signal of the two.
To look at headset sessions only, select the native runtimes rather than trying to exclude the browser ones:
- Headset sessions:
runtime_host: ["native_standalone", "native_tethered"] - Browser sessions:
runtime_host: ["web_browser", "webxr"]
You can ask for this conversationally — "what's the FPS score for headset sessions only, excluding WebGL?" — and the assistant will apply the right filter.
Filtered results cover classified sessions only
Device classification is applied as sessions are processed, and older sessions are still being backfilled. A session that has not been classified yet carries none of these device fields, so any device filter excludes it. Filtered responses say so explicitly. Coverage grows as the backfill progresses; for an unfiltered view of what has been classified so far, ask for the device distribution without a filter.
Available Tools
| Tool | Purpose |
|---|---|
get_scene_sessions |
Session data, device analytics, and engagement metrics for a scene |
If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.