API Reference

Quickstart

Six self-contained objectives — copy-pastable examples that each evidence a real use of the API.

Each section below answers one practical question. They share an auth prerequisite (covered first) and otherwise stand alone — you don’t need to read them in order.

Prerequisites

You’ll need a client ID, client secret, token issuer URL, and API audience identifier from your Aura Vision account manager. Exchange them for a JWT once via OAuth2 client_credentials (see Authentication for the full flow):

curl -X POST https://<your-issuer>/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"…","client_secret":"…","audience":"…","grant_type":"client_credentials"}'

Use the returned access_token as a Bearer token on the Core API, or as a ?token= query parameter on the Metrics WebSocket. You’ll also need a location ID — list them via GET /v1/location/list once and pick one.

The examples below use 64a1b2c3d4e5f6a7b8c9d0e3 as the location ID.

Pull last week’s footfall

Goal: Daily counts of people entering a specific location over the past 7 days.

This is the headline number for any retail dashboard. Sent over the Metrics WebSocket — connect to wss://ws.auravision.ai?token=<your_token> and send:

{
  "action": "metric",
  "data": {
    "id": "req-footfall",
    "route": "entries",
    "body": {
      "start": "2024-04-01T00:00:00.000Z",
      "end":   "2024-04-07T23:59:59.000Z",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location",
      "facets": ["segments", "summary"],
      "aggregationPeriod": "day"
    }
  }
}

Response (pipe-delimited frame, single part):

req-footfall|0|0|{
  "segments": [
    { "index": "2024-04-01T00:00:00.000", "location": "64a1b2c3d4e5f6a7b8c9d0e3", "entries": 1284 },
    { "index": "2024-04-02T00:00:00.000", "location": "64a1b2c3d4e5f6a7b8c9d0e3", "entries": 1102 }
  ],
  "summary": [
    { "location": "64a1b2c3d4e5f6a7b8c9d0e3", "entries": 8234 }
  ],
  "meta": { "units": { "entries": "peopleCount" } }
}

→ Full schema, demographics, and the estimates facet on Traffic > Entries.

Find where visitors spend time

Goal: Compare dwell across multiple zones in a single request, ranked by stickiness.

Zones (fitting rooms, departments, checkouts) are identified by taxonomy strings — see FAQ > What’s a taxonomy?. You discover what’s available, then query several of them in one call.

Step 1 — list the configured areas. Same WebSocket connection:

{
  "action": "detail",
  "data": {
    "id": "req-areas",
    "route": "detail/list",
    "body": {
      "returnEntityType": "area_context",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location"
    }
  }
}
req-areas|0|0|[
  { "area_type": "taxonomy", "taxonomy": "Service:Fitting Rooms",       "recording_id": "…" },
  { "area_type": "taxonomy", "taxonomy": "Service:Checkout",            "recording_id": "…" },
  { "area_type": "taxonomy", "taxonomy": "Products:Clothing:Shoes",     "recording_id": "…" }
]

Step 2 — query dwell across all of them. Pass every taxonomy you want compared and add taxonomy to breakdownByDimensions so the response splits per zone:

{
  "action": "metric",
  "data": {
    "id": "req-dwell-cmp",
    "route": "area/data",
    "body": {
      "start": "2024-04-01T00:00:00.000Z",
      "end":   "2024-04-07T23:59:59.000Z",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location",
      "areaType": "taxonomy",
      "taxonomy": ["Service:Fitting Rooms", "Service:Checkout", "Products:Clothing:Shoes"],
      "facets": ["summary"],
      "aggregationPeriod": "day",
      "breakdownByDimensions": ["taxonomy"]
    }
  }
}
req-dwell-cmp|0|0|{
  "summary": [
    { "taxonomy": "Service:Fitting Rooms",   "area_total_entries": 184, "area_average_dwell_time": 146 },
    { "taxonomy": "Service:Checkout",        "area_total_entries": 902, "area_average_dwell_time":  62 },
    { "taxonomy": "Products:Clothing:Shoes", "area_total_entries": 411, "area_average_dwell_time":  98 }
  ],
  "meta": { "units": { "area_total_dwell_time": "seconds", "area_average_dwell_time": "seconds" } }
}

One call, three zones, ranked side-by-side: fitting rooms have the longest average visit (146s), checkout the shortest (62s).

→ Area taxonomy · Area average dwell

How long do 25–34 year-old women spend in store?

Goal: Pull store-wide dwell for a specific age × gender demographic.

Most metric routes accept demographic filters. Add breakdownByDimensions for each axis you want to filter on, then pass the matching ages / genders / roles arrays. Filtering and breaking down are the same parameter — if you only want one value, list one value:

{
  "action": "metric",
  "data": {
    "id": "req-demo-dwell",
    "route": "average-dwell-time",
    "body": {
      "start": "2024-04-01T00:00:00.000Z",
      "end":   "2024-04-30T23:59:59.000Z",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location",
      "areaType": "location-dwell",
      "facets": ["summary"],
      "aggregationPeriod": "month",
      "breakdownByDimensions": ["age", "gender"],
      "ages": ["25_34"],
      "genders": ["female"]
    }
  }
}
req-demo-dwell|0|0|{
  "summary": [
    { "age": "25_34", "gender": "female", "average_dwell_time": 384 }
  ],
  "meta": { "units": { "average_dwell_time": "seconds" } }
}

25–34 year-old women spent 384 seconds (~6m24s) in the store on average.

Demographics are visual estimates from the analytics pipeline — see FAQ > What demographic values can I filter on? for the full enums.

→ Dwell time

Compare staff vs customer dwell at the tills

Goal: See how long staff spend at the checkout zone versus customers — useful for staffing or service-level analysis.

Filter by role and break down by it so both values appear in the response. The roles enum distinguishes customer, staff, and three “interaction” roles for proximity analytics:

{
  "action": "metric",
  "data": {
    "id": "req-till-roles",
    "route": "area/data",
    "body": {
      "start": "2024-04-01T00:00:00.000Z",
      "end":   "2024-04-30T23:59:59.000Z",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location",
      "areaType": "taxonomy",
      "taxonomy": ["Service:Checkout"],
      "facets": ["summary"],
      "aggregationPeriod": "month",
      "breakdownByDimensions": ["role"],
      "roles": ["customer", "staff"]
    }
  }
}
req-till-roles|0|0|{
  "summary": [
    { "role": "customer", "area_total_entries": 4218, "area_average_dwell_time":  72 },
    { "role": "staff",    "area_total_entries":   84, "area_average_dwell_time": 612 }
  ],
  "meta": { "units": { "area_average_dwell_time": "seconds" } }
}

Customers pass through in about a minute; staff spend ~10 minutes per shift instance at the till.

→ Area average dwell · FAQ > Demographic values

Check sales conversion rate

Goal: Transactions per visitor over a date range — campaign assessment, store-effectiveness benchmarking.

Conversion lives on the Metrics API too. Sales data is demographic-free (POS records carry no visitor attributes), so include entity in breakdownByDimensions:

{
  "action": "metric",
  "data": {
    "id": "req-conv",
    "route": "transactions/conversion-rate",
    "body": {
      "start": "2024-04-01T00:00:00.000Z",
      "end":   "2024-04-30T23:59:59.000Z",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location",
      "facets": ["summary"],
      "aggregationPeriod": "month",
      "breakdownByDimensions": ["entity"]
    }
  }
}
req-conv|0|0|{
  "summary": [
    { "location": "64a1b2c3d4e5f6a7b8c9d0e3", "sales_conversion_rate": 0.184 }
  ],
  "meta": { "units": { "sales_conversion_rate": "rate" } }
}

18.4% of visitors transacted in April.

→ Sales > Conversion rate

See which cameras are live now

Goal: Real-time online/offline status for every recording on a location.

Unlike historic metrics (10-minute refresh cadence), status/uptime is a real-time snapshot — useful for ops dashboards and on-call paging:

{
  "action": "status",
  "data": {
    "id": "req-live",
    "route": "status/uptime",
    "body": {
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location"
    }
  }
}
req-live|0|0|[
  {
    "recording_id": "64a1b2c3d4e5f6a7b8c9d0e4",
    "location_id":  "64a1b2c3d4e5f6a7b8c9d0e3",
    "status": "online",
    "last_seen_utc": "2024-04-15T10:14:00.000Z",
    "average_quality": 0.97
  },
  {
    "recording_id": "64a1b2c3d4e5f6a7b8c9d0e5",
    "location_id":  "64a1b2c3d4e5f6a7b8c9d0e3",
    "status": "offline",
    "last_seen_utc": "2024-04-15T08:32:00.000Z",
    "average_quality": 0.88
  }
]

→ Realtime uptime

Where to go next