Query Site Analytics

This article shows how to read a site's analytics with the Semantic Model API. A semantic model describes one analytics subject area (such as site traffic, revenue, etc.) and defines the measures, dimensions, and parameters you can query.

Prerequisites

1. The app/caller has the Site Analytics – read permission scope (SCOPE.DC-ANALYTICS-AND-REPORTS.READ-SITE-ANALYTICS).
2. A site context is available (the request is authorized against a specific site).

Required APIs

• Semantic Model API: REST
• Site Properties API (for the site's time zone): REST

Base path: https://www.wixapis.com/analytics/semantic-model/v3

Decision flow

Always follow List → Get → Query. You cannot construct a valid query without first discovering the model's field names from Get Semantic Model.

1. List Semantic Models — discover which subject areas exist and their IDs.
2. Get Semantic Model — inspect a model's measures, dimensions, and parameters to find the exact name values to query and their supported filters/sorting.
3. Query Semantic Model Data — request specific field names for a time interval, with optional filters, sorting, paging, and formatting.

Before you begin (sharp edges)

• interval is required on every query. There is no way to query without a date range — omitting it fails.
• interval is start-inclusive, end-exclusive ([start, end)). start is included, end is not. To get all of January 2026, query start: "2026-01-01..." and end: "2026-02-01..." — you get Jan 1–31, and Feb 1 is excluded. Set end to the day after the last day you want.
• Set interval.timezone to the site's time zone to match the Wix dashboard. Analytics in the Wix business manager are bucketed by the site's time zone. If interval.timezone is omitted it defaults to UTC, so day boundaries shift and your numbers won't match what the owner sees in the dashboard (and the same goes for using a different time zone). Get the site's IANA time zone from properties.timeZone via Get Site Properties (GET https://www.wixapis.com/site-properties/v4/properties) and pass it through.
• Field names must come from Get Semantic Model. The fields, filters[].field, and sort.fieldName values must exactly match a name returned by the model schema (e.g. traffic.sessions_count). Do not guess field names.
• Field dependencies. A field returns data only if at least one of the field names in its dependencies array is also included in the same query; otherwise it's silently omitted from results (no error). For example, a measure may only return data when a specific dimension is also requested.
• Result cap: 1,000 rows per query. results is capped at 1,000 rows — paginate with paging.offset for larger datasets.
• Formatting is opt-in. Set formattingEnabled: true to also receive a human-readable formattedValue per cell (e.g. 1500 → "$1,500.00" or 1.5K). Raw typed values are always returned.
• Totals are opt-in. Set totalsIncluded: true to get a totals row summing numeric fields across the full (unpaginated) result set.
• Unique fields are not additive. For unique measures (e.g. unique visitors), query the exact time range you want in a single request — never sum values from separate date-range queries. Uniques are deduplicated within each queried range, so adding per-range results double-counts anyone who appears in more than one range and overstates the true total.

Step 1: List semantic models

Response:

Pick the model whose subject area matches the request, and keep its id.

Step 2: Get the model schema

Response shape:

Each Field (in measures, dimensions, and parameters):

• Measures are quantitative fields you aggregate (revenue, page views, order count).
• Dimensions are categorical fields you group by (traffic source, country, product name).
• Parameters are optional inputs that customize query behavior (currency, date granularity).

Step 3: Query the model data

POST /semantic-models/query-data (body requires Content-Type: application/json).

Required body fields: semanticModelId, interval, fields.

Request fields

Response shape

Each cell in results[].fields is a typed value — one of numericValue, stringValue, booleanValue, timestampValue, arrayValue, or objectValue — plus formattedValue when formattingEnabled is true. totals is present only when totalsIncluded is true.

Time zone (match the Wix dashboard)

Analytics shown in the Wix business manager are aggregated by the site's time zone. To return numbers that match what the site owner sees, pass that time zone in interval.timezone on every query. When timezone is omitted, the API defaults to UTC — which shifts day boundaries and produces totals that don't line up with the dashboard (the same applies to any non-site time zone).

Get the site's time zone from Get Site Properties:

The IANA time zone string is returned in properties.timeZone:

Use that value as interval.timezone in Query Semantic Model Data. The Site Properties timeZone reflects the site's primary business address and requires the SITE_SETTINGS.VIEW permission.

Pagination

To retrieve more than 1,000 rows, page through with offset:

1. Request page 1 with paging: { limit: 1000, offset: 0 }.
2. Increment offset by the page size until pagingMetadata.count is less than the requested limit.

Common Errors

Silent gap (no error): a requested field returns no data because none of its dependencies were included in the query — add a dependency field and re-query.

Best Practices

1. Always run List → Get → Query; never hardcode field names — read them from Get Semantic Model.
2. Pass the site's time zone (properties.timeZone from Get Site Properties) in interval.timezone so results match the Wix dashboard.
3. Include a field's dependencies in the query, or expect that field to be silently dropped.
4. Use formattingEnabled: true for anything shown directly to a user; keep raw values for calculations.
5. Use totalsIncluded: true to get period totals alongside a paged breakdown in a single call.
6. Keep fields minimal (projection) and paginate large result sets with offset.

Related Documentation

• Semantic Model API: Introduction
• Semantic Model API: Sample Flows
• List Semantic Models
• Get Semantic Model
• Query Semantic Model Data
• Get Site Properties (source of the site's timeZone)