Charts and visualization
Chart tools turn a question into a chart. Ask your AI assistant to show, chart, or plot something, and the server returns a chart specification in the Cognitive3D theme that your client draws.
Use these tools when you want to see the data. When you want numbers to read or quote, the assistant uses the summary tools described on the organization, project, session, and objective pages instead.
Tips
- Say what you want to see: Words like "show me", "chart", "plot", "heatmap", and "funnel" tell the assistant to use a chart tool.
- Name the framing: "Share of", "top 10", "distribution of", and "X versus Y" each lead to a different chart type.
- Give a date range: Most charts cover the last 30 days unless you ask for another range.
- Ask what is available: The assistant can list a project's fields and their values before it builds a chart, so you do not need to know field names.
How charts appear in your client
The server returns charts as Vega-Lite specifications.
- Claude Desktop and claude.ai draw the chart in the conversation.
- Claude Code runs in a terminal and cannot draw Vega-Lite directly. Ask the assistant to save the chart as an image file, or to show the values as a table.
- Other clients vary. If your client cannot draw the specification, the assistant can rebuild the chart from the values in it.
When the data does not suit a chart, the tool returns a table instead.
Chart any field
query_data is the general-purpose chart tool. It counts sessions or events, or sums, averages, and finds the minimum or maximum of a numeric field. You can group by up to two fields and filter by any field.
Sample queries for charting any field
- "Chart sessions per week for project 431 over the last 90 days."
- "Show me the share of sessions by headset model."
- "What are the top 10 custom events by count this month?"
- "Plot the distribution of session duration."
- "Show average session duration by app version, only for sessions longer than one minute."
Finding fields
Two helper tools let the assistant discover what it can chart:
list_slicer_fieldslists a project's queryable fields, including your own session properties and event properties.get_field_valueslists the distinct values of one field, which is useful for building filters.
Parameters for charting any field
| Parameter | Required | Description |
|---|---|---|
project_id |
Yes | The numeric project ID. |
op |
Yes | The aggregation: sessionCount, eventCount, sum, average, min, max, or groups. |
metric_field |
No | The numeric field to aggregate, for sum, average, min, and max. |
group_by |
No | Up to two fields to group by. Date fields group by day, week, month, quarter, or year. |
filters |
No | Conditions on any field, such as equals, greater than, or is not empty. |
start_date / end_date |
No | Date range in Unix milliseconds or ISO 8601. Defaults to the last 30 days. |
output_format |
No | vegalite for a chart, table for a full table, or text (default) for raw values. |
intent |
No | The framing: part_to_whole, ranking, process_sequence, distribution, correlation, or deviation. |
Purpose-built charts
These tools each draw one kind of chart. The assistant chooses one when your question matches it.
| Ask for | Tool | What you get |
|---|---|---|
| "Plot session duration against frame rate." | query_relationship |
A scatter plot of two numeric measures, one point per session. |
| "Where do users drop off in the onboarding objective?" | query_objective_funnel |
A step-by-step funnel for one multi-step objective. |
| "What drives the comfort score?" | query_metric_profile |
A radar chart of a score's component sub-scores. |
| "Chart my exit survey results." | query_exitpoll |
One chart per question, chosen to suit the question type. |
| "Which way do users face?" | query_head_orientation |
A radial profile of head orientation in physical and virtual space. |
| "Show a gaze heatmap of the Showroom scene." | query_spatial_heatmap |
A top-down heatmap of gaze, fixation, or position on a scene's floor plane. |
| "Where in the world are my users?" | query_geo_distribution |
A world map of sessions by country. |
| "What headsets do my users have?" | query_hierarchy |
A treemap of device category and family. |
| "How do users move between scenes?" | query_scene_flow |
A flow diagram of which scene participants visit first, second, and third. |
Notes on purpose-built charts
query_metric_profileacceptspresence,performance,comfort, orcyberwellness.query_spatial_heatmapworks on one scene at a time. Choosegaze(default),fixation, orposition, and optionally a cell size in meters (default 0.5).query_head_orientationneeds an SDK version that records head orientation. The tool tells you when the data is absent.query_scene_flowcovers all time and needs at least two scenes and participants with more than one session.query_objective_funnelandquery_exitpollpick the objective or survey automatically when a project has only one. Otherwise they list the choices.
Available tools
| Tool | Purpose |
|---|---|
query_data |
Chart or tabulate any field, with grouping and filters. |
list_slicer_fields |
List a project's queryable fields. |
get_field_values |
List the distinct values of a field. |
query_relationship |
Scatter plot of two measures per session. |
query_objective_funnel |
Step funnel for one objective. |
query_metric_profile |
Radar chart of a score's sub-scores. |
query_exitpoll |
Charts of ExitPoll survey responses. |
query_head_orientation |
Radial profile of head orientation. |
query_spatial_heatmap |
Top-down heatmap of a scene. |
query_geo_distribution |
World map of sessions by country. |
query_hierarchy |
Treemap of devices. |
query_scene_flow |
Flow of scene visits. |
See also
- ExitPoll surveys — charting survey responses.
- Zones — using a position heatmap to place zones.
- Metrics Glossary — definitions of the scores you can chart.
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.