Skip to content

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_fields lists a project's queryable fields, including your own session properties and event properties.
  • get_field_values lists 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_profile accepts presence, performance, comfort, or cyberwellness.
  • query_spatial_heatmap works on one scene at a time. Choose gaze (default), fixation, or position, and optionally a cell size in meters (default 0.5).
  • query_head_orientation needs an SDK version that records head orientation. The tool tells you when the data is absent.
  • query_scene_flow covers all time and needs at least two scenes and participants with more than one session.
  • query_objective_funnel and query_exitpoll pick 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

intercom 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.