> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.
# QR analytics
> POST /analytics/qr/
Returns aggregated scan analytics for one or more QR codes, grouped by whichever metric type(s) you request.
This is a **POST-only** endpoint despite the name suggesting a lookup — a `GET` request returns `405 Method Not Allowed`. The query parameters (`from`, `to`, `type`) select the date range and metrics; the request body selects which QR codes to include.
Requires a Management API key with `MANAGEMENT_API` (or `MANAGEMENT_API_SANDBOX`) quota — see the [Management API overview](/api-reference/management-api/overview) — plus the account's own `QR_ANALYTICS_BASIC` quota. Requesting anything beyond the `count` metric additionally requires `QR_ANALYTICS_ADVANCED`; without it, every request is silently downgraded to `count` regardless of the `type` you asked for.
## Request
```bash cURL theme={null}
curl --request POST \
--url 'https://management.scanova.io/analytics/qr/?from=2026-07-01&to=2026-08-16&type=qr' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"q": ["Q07afe81aa0034c01"],
"filter_by": "qrid"
}'
```
```json 200 theme={null}
{
"qr": [],
"qr_meta": {
"docs-v2-first-qr-code": {
"qrid": "Q07afe81aa0034c01",
"category": "Website URL",
"category_slug": "url"
}
}
}
```
Verified live — an empty `qr` array here reflects a QR code with zero scans in the requested window, not an error. `qr_meta` is an extra `name -> {qrid, category, category_slug}` map, added only when `qr` is among the requested `type`s, so a caller can deep-link from a name-keyed row back to its `qrid`. It's additive: the shape callers already parse under each metric key is unchanged.
### Query parameters
Start date (`YYYY-MM-DD`), inclusive.
End date (`YYYY-MM-DD`), inclusive.
Comma-separated metric types, e.g. `qr,device,geography`. Common values: `count`, `qr`, `date`, `day`, `time`, `utm`, `device`, `os`, `browser`, `handset`, `geography`, `geo_location`, `age`. Requires the account's `QR_ANALYTICS_ADVANCED` quota for anything beyond `count`.
Grouping for time-series metric types, e.g. `date`, `week`, `month`.
Excludes scans identified as bot traffic from the results.
Pass `true` for dashboard-overview-style calls — bypasses the QR-count/date-range volume limit described below, and doesn't count toward the account's "analytics fetched" activity signal.
### Request body
List of identifiers to scope the analytics to — the type of identifier depends on `filter_by`.
One of `qrid` (QR code IDs), `id` (internal numeric IDs), `tags` (tag names), or `folder` (folder IDs).
### Response
The response is an object keyed by each requested metric `type`, plus `qr_meta` when applicable (see above). Shape varies per metric type — `count` returns scan totals, `device`/`os`/`browser`/`geography` return breakdowns by that dimension, and time-series types (`date`/`day`/`time`) return a series bucketed by `group`.
Requesting too many QR codes over too wide a date range returns a `400` under `q`: `"High Volume of data. Either select lower than {N} QR Codes/{N} days time period or generate Analytics Export instead."` In practice, both [Export analytics](/api-reference/management-api/analytics/export) and [Export raw analytics](/api-reference/management-api/analytics/export-raw) enforce the exact same limit — all three endpoints share the same request-validation code path — so the actual fix for this error is narrowing `q` or the date range, not switching endpoints.
## Related
* [Export analytics](/api-reference/management-api/analytics/export) — download the same kind of aggregated metrics as a file instead of a JSON response.
* [Export raw analytics](/api-reference/management-api/analytics/export-raw) — download row-level scan records instead of aggregated breakdowns.
* [Management API overview](/api-reference/management-api/overview) — the auth scheme and quota architecture this endpoint is part of.
## OpenAPI
````yaml api-reference/openapi/management-api.json POST /analytics/qr/
openapi: 3.1.0
info:
title: Scanova Management API (v2)
description: >-
The complete Scanova Management API — every endpoint available at
management.scanova.io (QR codes, folders, tags, leads, forms, analytics,
plans, shared users & roles), plus the token-creation and usage-stats
endpoints used to authenticate against it. Every path and request/response
shape below was verified live against a real API key and the actual running
backend (Phase 7, 2026-08-16) — not guessed from reading urls.py alone.
version: 2.0.0
servers:
- url: https://management.scanova.io
description: Management API — QR/folder/tag/lead/form/analytics/plans endpoints
security:
- apiKeyAuth: []
paths:
/analytics/qr/:
post:
summary: QR analytics
description: >-
Returns aggregated analytics data. Requires `from` and `to` as query
parameters (dates) and a `type` query parameter (comma-separated metric
types, e.g. `qr`). The request body selects which QR codes to include
via `q` (a list of identifiers) and `filter_by` (which identifier type
`q` contains — `qrid` is the default; `tags`, `id`, and `folder` are
also supported). Requesting too many QR codes over too wide a date range
returns a 400 under `q` — the same volume cap applies to
/analytics/qr/export/ and /analytics/qr/raw/, which share this
endpoint's request-validation code.
operationId: getManagedQrAnalytics
parameters:
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: type
in: query
required: true
schema:
type: string
description: Comma-separated metric types, e.g. `qr`.
- name: group
in: query
schema:
type: string
default: date
description: Grouping for time-series metric types, e.g. date/week/month.
- name: exclude_bot_scan
in: query
schema:
type: boolean
default: false
- name: overview
in: query
schema:
type: boolean
description: Bypasses the volume cap; used by dashboard overview widgets.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
q:
type: array
items:
type: string
description: >-
Query data — a list of identifiers of the type named in
filter_by.
filter_by:
type: string
enum:
- qrid
- tags
- id
- folder
default: qrid
required:
- q
example:
q:
- Q07afe81aa0034c01
filter_by: qrid
responses:
'200':
description: >-
Analytics data, grouped by the requested type(s). A `qr_meta`
name->{qrid, category, category_slug} map is attached whenever `qr`
is among the requested types.
content:
application/json:
example:
qr: []
qr_meta:
docs-v2-first-qr-code:
qrid: Q07afe81aa0034c01
category: Website URL
category_slug: url
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Send your Management API key as the raw value of the Authorization
header — no "Bearer " or "Token " prefix, and no other characters.
Example: `Authorization: 401f7ac837da42b97f613d789819ff93537bee6a`. A
header containing more than one space-separated part is rejected
outright. Requests also require the request's Host header to be the
management API host (e.g. management.scanova.io) — the same key sent to
the regular API host will not authenticate.
````