---
title: "Get audience breakdowns"
method: GET
path: "/v3/web-analytics/audience"
tags: ["Web Analytics"]
---

# Get audience breakdowns

`GET /v3/web-analytics/audience`

Device and approximate location breakdowns with privacy-suppressed region, city and map data. Requires web_analytics:read. The authenticated credential determines the business; no business_id override is accepted. Reporting and scope-option calls share a 600-request/hour limit per API key or OAuth installation, in addition to the normal burst and hourly limits. Responses contain recorded analytics, which may be lower than actual traffic because of consent choices, self-traffic exclusion, blockers, and unavailable attribution.

## Query parameters

- `from` string, date, required
- `to` string, date, required
- `timezone` string
- `store_id` integer
- `entity_type` 'landing_page' | 'product' | 'bundle_price_option' | 'store_home' | 'cart' | 'checkout' | 'payment_link' | 'order_detail' | 'order_success' | 'order_invoice' — Customer-facing page surface. The owner is a landing page, product, bundle price option, store, or protected payment-link scope; order surfaces use the store owner, never an order ID.
- `entity_id` string
- `entity_path` string
- `page_id` integer
- `page_host` string
- `page_path` string
- `ad_click` 'paid' | 'organic' | 'meta' | 'google' | 'tiktok'
- `limit` integer

## Response `200`

Success

- WebAnalyticsAudience — Locations are approximate IP estimates, not device GPS. Region, city and map-point buckets require at least five distinct identified visitors and are each capped at 100 after suppression. Devices and countries use their full dimension breakdowns.
  - `devices` WebAnalyticsAudienceBucket[], required
    - `bucket` string, required
    - `views` integer, required
    - `visitors` integer, required
  - `countries` WebAnalyticsAudienceBucket[], required
    - `bucket` string, required
    - `views` integer, required
    - `visitors` integer, required
  - `regions` WebAnalyticsAudienceBucket[], required
    - `bucket` string, required
    - `views` integer, required
    - `visitors` integer, required
  - `cities` WebAnalyticsAudienceBucket[], required
    - `bucket` string, required
    - `views` integer, required
    - `visitors` integer, required
  - `map_points` WebAnalyticsMapPoint[], required
    - `label` string, required
    - `latitude` number, required
    - `longitude` number, required
    - `views` integer, required — Distinct recorded page views.
    - `visitors` integer, required — Distinct identified visitors; anonymous events do not create visitor identities.
    - `sessions` integer, required — Distinct identified sessions.
  - `location_metadata` object, required
    - `regions` WebAnalyticsLocationCoverage, required
      - `limit` 100, required
      - `returned_buckets` integer, required
      - `total_buckets` integer, required — Eligible buckets after privacy suppression, before the output cap.
      - `truncated` boolean, required
    - `cities` WebAnalyticsLocationCoverage, required
      - `limit` 100, required
      - `returned_buckets` integer, required
      - `total_buckets` integer, required — Eligible buckets after privacy suppression, before the output cap.
      - `truncated` boolean, required
    - `map_points` WebAnalyticsLocationCoverage, required
      - `limit` 100, required
      - `returned_buckets` integer, required
      - `total_buckets` integer, required — Eligible buckets after privacy suppression, before the output cap.
      - `truncated` boolean, required
  - `location_basis` 'ip_estimate', required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests. Storefront public requests using `X-Scalev-Storefront-Api-Key` or `X-Scalev-Guest-Token` are rate-limited as direct client/browser requests. Machine-authenticated business requests are rate-limited per API key or OAuth installation. Rate-limit responses may be plain text instead of the normal JSON error shape.

## Changes

- **2026-09-20** `af4231e0cad9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/scalev/apis/nexus-commerce-api/changes/v3/web-analytics/audience/get.md)

---

[API](https://skmtc.dev/scalev/apis/nexus-commerce-api.md) · [All operations](https://skmtc.dev/scalev/apis/nexus-commerce-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalev/apis/nexus-commerce-api/revisions/215156c4eee0?raw)