Metrics API overview

The Metrics API delivers analytics — footfall, dwell, occupancy, transactions, heatmaps, demographics. It uses a single authenticated WebSocket connection that serves many sequential queries.

Base URL: wss://ws.auravision.ai

Prefer a single HTTPS request? The HTTP gateway exposes the same data over a request/response interface — POST a body that mirrors the WebSocket message shape, receive the consolidated response. Same JWT bearer auth as the Core API. Contact your account manager for the gateway endpoint.

Looking for organisation, location, or recording lookups over the same WebSocket? See Reference data — the WS analogue of the Core REST resource endpoints.

Conventions

• IDs are 24-character hexadecimal strings (MongoDB ObjectIDs). Top-level resources expose them as id; embedded objects as _id.
• Dates in metric body params (start, end) require full ISO 8601 with timezone, e.g. 2024-04-14T10:00:00.000Z. Date-only strings are rejected.
• Response framing — every message is a pipe-delimited frame {id}|{partNum}|{totalParts}|{JSON}. See Receive format.
• null vs zero — null means no data exists for the period (outside opening hours, or a rate is undefined). 0 means data was collected and the count was zero. Do not coerce null to 0.

All metrics

Traffic

Occupancy & Dwell

Lines

Areas

Sales

Heatmaps & Thumbnails

Uptime

Exports

Authentication

Present the JWT once at connection time as a ?token=<your_token> query parameter on the WebSocket URL — connect to wss://ws.auravision.ai?token=<your_token>. Do not include it on individual messages. See Authentication for the token flow.

Send format

{
  "action": "metric",
  "data": {
    "id": "your-client-request-id",
    "route": "entries",
    "body": { }
  }
}

Receive format

{id}|{partNum}|{totalParts}|{JSON}

Each frame is a pipe-delimited string. The first three segments are the request id (echoed back), the part number, and the total part count. The remainder of the line is the JSON payload.

• Single-part responses use 0|0 as a sentinel — the entire JSON is in this one frame. Example: req-001|0|0|{"segments":[...],"summary":{...}}
• Multi-part responses are 1-indexed up to totalParts. Buffer parts by id and concatenate the JSON segments once you’ve received partNum === totalParts. Example: req-001|1|3|{...} → req-001|2|3|{...} → req-001|3|3|{...}

Large datasets

For very large responses (above ~260,000 segments), the segments field of the assembled JSON will be a signed download URL rather than inline JSON. Fetch it with a standard GET. The file is CSV: the first row contains column names; downstream rows are data, with unit-type hints encoded alongside the column values where coercion between numeric and string is needed. Refer to the column ordering you supplied in the request (or the default ordering for inline segments) to interpret the file.

Common request body fields

These apply to most metric routes. Endpoint pages document only fields specific to their routes.

facets options

Aggregation period options

The aggregationPeriod field accepts one of these values:

Querying in-progress periods

Querying an in-progress monthly, weekly, quarterly, or yearly period returns data accumulated so far — it is not empty. Each period is represented by its start date. If your query’s start date is after the beginning of the current period, that period will not appear in results.

Example: Querying 2026-03-17 to 2026-04-15 at monthly granularity returns April data only — not March. The March period starts on 2026-03-01, which falls before your query range. To include March, set the start date to 2026-03-01 or earlier.

Where to go next

• Entries — start with footfall
• Line entries — entries across zone lines
• Area entries — area-based engagement
• Transactions — POS metrics