Skip to content

Zones

Zone tools let you read a project's zones and visit statistics through an AI assistant, and create zones from a description instead of drawing them by hand. This is useful when you have many scenes, or scenes that are generated, where drawing each zone on the dashboard is impractical.

A zone is a named region of a scene built from one or more shapes. For how zones work, including visit types, the Zones report, and zone objectives, see Zones in the dashboard documentation. These tools manage the same zones you see on the dashboard's Zones page.

Zones only count visits in new sessions

Cognitive3D counts visits only for sessions recorded after a zone is saved. It does not reprocess earlier sessions, so a new zone starts with no visits, and a draft never counts visits. To explore sessions you have already recorded, see Explore sessions recorded before a zone existed.

Tips

  • Start with what exists: Use list_zones to see the zones and shapes already defined on a project.
  • Create drafts first: By default, new zones are created as drafts that you review on the dashboard before they count visits.
  • Give the assistant a reference: The MCP Server does not send the assistant your scene's geometry. It places zones well when it works alongside your Unity or Unreal project, when sessions have been recorded on the scene, or when one or two zones already mark known landmarks.
  • Dry runs: Creating and deleting preview what will happen first. Nothing is written until you confirm. Renaming a zone applies immediately.
  • Write access: Creating, renaming, and deleting require an organization-admin or project-admin role. Read-only organization API keys can view zones but not change them.

List zones and shapes

list_zones shows every zone on a project, with each shape's scene and a one-line summary of its geometry. list_shapes shows the shapes drawn on one scene and which zones each belongs to, including draft shapes that are not in a zone yet.

Sample queries for listing zones

  • "Which zones are defined on project 431, and what shapes make them up?"
  • "List the shapes on the Warehouse scene."
  • "Are there any draft shapes that aren't in a zone yet?"

Parameters for listing zones

Tool Parameter Required Description
list_zones project_id Yes The numeric project ID.
list_shapes project_id Yes The numeric project ID.
list_shapes scene_id Yes The scene ID (obtained from project details).

Get zone visits

get_zone_visits reports how participants used each zone.

Sample queries for zone visits

  • "How many sessions visited the Treasure Chest zone, and how long did they stay?"
  • "Which zone has the longest average visit this month?"

Response for zone visits includes

  • Visits: continuous stretches with the participant's head inside the zone. Stretches shorter than 500 ms are not counted.
  • Visiting sessions, and their share of all sessions in the date range.
  • Mean visit length and total dwell time.
  • The date each zone was saved, for zones with no visits yet.

Keep these points in mind when you read the results:

  • The default date range is all time. Because a zone only has visits for sessions recorded after you saved it, "all time" in practice means "since the zone was saved".
  • The share of sessions can look low. The share is calculated over every session in the date range, including sessions recorded before the zone was saved, which can never have a visit. For a fair share, ask for a date range that starts on the day the zone was saved.
  • Visits are head-position visits. This tool does not report the gazed-in or gazed-through visit types described in Visit types.
  • Total dwell does not add up across zones, because zones can overlap.

Explore sessions recorded before a zone existed

Zone visits cannot tell you what happened in an area before its zone was saved. To look at earlier sessions:

  • Ask for a position or gaze heatmap of the scene. query_spatial_heatmap uses the positions and gaze already recorded in your sessions, so it covers sessions from before any zone existed. It covers the last 30 days and the scene's latest version unless you ask for a wider date range.
  • Use Analyze on the dashboard's Zones page to count recorded gaze, head position, or events inside a shape.

Parameters for zone visits

Parameter Required Description
project_id Yes The numeric project ID.
zone_id No Restrict the results to one zone. Defaults to all zones.
start_date / end_date No Session date range in ISO 8601. Defaults to all time.

Create a zone

create_zone_from_shapes creates the shapes and the zone in one step. If any part fails, the tool removes what it created.

By default the zone is a draft. The tool creates the shapes as a draft group named after the zone and returns a link to the dashboard's Zones page for that scene. Review the geometry there, drawn over your scene, and press Save changes to publish it. Drafts do not count visits.

Warning

Save changes publishes every draft on that scene, not only the one you just created. The tool tells you when other drafts exist on the scene.

To create the zone immediately without a review, ask the assistant to publish it. This sets publish to true and suits scripted, bulk definitions.

To group shapes that already exist into a zone, the assistant uses create_zone with their shape IDs.

Sample queries for creating a zone

  • "Create a draft zone called Spawn on the Lobby scene: a 2 by 2 meter floor area centered at x 0, z 3, rotated 45 degrees."
  • "Look at where people stand in the Showroom scene and propose draft zones for the three busiest areas."
  • "Publish a zone called Checkout from shapes 81 and 82."

Placing shapes

Positions and sizes are in meters, in the same coordinate frame as your scene, with Y up. Rotation is a yaw in degrees around the vertical axis.

Shape type Use it for Dimensions
INF_TALL_BOX A rectangular floor area at any height. width, length
INF_TALL_CYLINDER A circular floor area at any height. radius
BOX A box with a set height. width, height, length
CYLINDER A cylinder with a set height. radius, height
SPHERE A sphere. radius

For the two floor-area types, height is ignored. For BOX, CYLINDER, and SPHERE, you must give the height of the shape's center. For example, a 2 meter box centered at a height of 0 spans from 1 meter below the floor to 1 meter above it, so a standing participant's head is never inside it.

If you do not know the coordinates, the assistant can find them in these ways:

  • A coding agent that is open in your Unity or Unreal project can read object positions from the scene directly.
  • A position heatmap from query_spatial_heatmap shows where participants stand and walk, in the same coordinate frame.
  • Existing zones and shapes from list_zones and list_shapes name known places.

Parameters for creating a zone

Parameter Required Description
project_id Yes The numeric project ID.
name Yes The zone name.
shapes Yes The shapes to create. Each has a scene ID, shape type, name, center position, and dimensions.
description No A description for the zone. Applies when publishing.
publish No false (default) creates a draft for review. true creates the zone immediately.
confirm No Set by the assistant after you approve the preview.

Rename or delete a zone

update_zone renames or re-describes a zone, and applies immediately. delete_zone deletes a zone, and can also delete its shapes. create_shape and delete_shape work on single shapes.

The platform enforces these rules:

  • You cannot change which shapes a zone contains. Delete the zone and create it again.
  • You cannot delete or reshape a shape that belongs to a zone. Delete the zone with its shapes instead.
  • You cannot delete a zone that an objective uses. Update or remove the objective step first.

Sample queries for renaming or deleting a zone

  • "Rename the Spawn zone to Starting area."
  • "Delete the test zone and its shapes."

Use a zone in an objective

After a zone is published, you can ask the assistant to create an objective with a zone step, such as "Create an objective where users spend at least 5 seconds in the Lobby zone." See Create an objective and Zone objectives.

Available tools

Tool Purpose
list_zones List every zone with its shapes.
list_shapes List the shapes on one scene, with zone membership.
get_zone_visits Visits, visiting sessions, mean visit, and total dwell per zone.
create_zone_from_shapes Create shapes and a zone together, as a draft or published (confirmation-gated).
create_zone Group existing shapes into a zone (confirmation-gated).
update_zone Rename or re-describe a zone (applies immediately).
delete_zone Delete a zone, and optionally its shapes (confirmation-gated).
create_shape Create one shape on a scene (confirmation-gated).
delete_shape Delete a shape that is not in any zone (confirmation-gated).

See also

  • Zones — concepts, the Zones report, and drawing zones on the dashboard.
  • Objective queries — creating objectives, including zone steps.
  • Charts — spatial heatmaps of where participants look, stand, and move.

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.