> ## 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.
# Export Raw Scan Data
> Download row-level scan logs for one or more QR codes, using the same filters as the aggregate analytics export endpoint. Ideal for custom BI pipelines, reconciliations, or detailed auditing.
## Description
The **Export Raw Scan Data** endpoint returns a flat dataset where each row equals one scan event. Use it when you need to rebuild your own pivot tables, send the data to a warehouse, or debug anomalies at the event level. The query parameters mirror those in the analytics export endpoint so you can reuse the same request builder.
## Query Parameters
| Parameter | Type | Required | Description |
| :----------------- | :-------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | ✅ Yes | Export mode. Use `raw` for all scan events (humans + bots), or `raw_bot` to export **only** bot scan events. |
| `from` | `string (YYYY-MM-DD)` | ✅ Yes | Inclusive start date for the export window. |
| `to` | `string (YYYY-MM-DD)` | ✅ Yes | Inclusive end date. Defaults to the current date when omitted. |
| `file_format` | `string` | ✅ Yes | Output format. Accepted values: `csv`, `xls`, `xlsx`. CSV is recommended for large pulls. |
| `exclude_bot_scan` | `boolean` | No | When `true`, bot scan rows are excluded from the raw export. Use alongside `type=raw` to get a clean human-only dataset. Defaults to `false`. |
### Supported `type` Values
| Value | Description |
| :-------- | :--------------------------------------------------------------------------------------- |
| `raw` | Export all individual scan events (human and bot traffic combined). |
| `raw_bot` | Export **only** bot scan events. Useful for auditing or removing bot traffic separately. |
## Request Body
| Field | Type | Required | Description |
| :---------- | :------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `filter_by` | `string` | ✅ Yes | Filter type — either `qrid` (QR code IDs), `tags` (tag names) and folder id. |
| `q` | `array` | ✅ Yes | List of QR IDs (if `filter_by=qrid`) or tags (if `filter_by=tags`) or folder id (if `filter_by=folder`) to include in the raw export. |
When using form-data, pass one `q` field per ID or tag (for example: `q=Qf94...`, `q=Qf95...`).
## Example Request
### **Export Raw Scan Data by QR IDs**
```bash theme={null}
curl -X POST "https://management.scanova.io/analytics/qr/raw/?type=raw&from=2025-10-28&to=2025-11-26&file_format=csv" \
-H "Authorization: YOUR_API_KEY" \
-F "filter_by=qrid" \
-F "q=Qf94b25d768294148" \
-F "q=Qf94b25d768294149"
```
### **Export Raw Scan Data by Tags**
```bash theme={null}
curl -X POST "https://management.scanova.io/analytics/qr/raw/?type=raw&from=2025-10-28&to=2025-11-26&file_format=csv" \
-H "Authorization: YOUR_API_KEY" \
-F "filter_by=tags" \
-F "q=marketing" \
-F "q=campaign"
```
### **Export Bot-Only Scan Data**
```bash theme={null}
curl -X POST "https://management.scanova.io/analytics/qr/raw/?type=raw_bot&from=2025-10-28&to=2025-11-26&file_format=csv" \
-H "Authorization: YOUR_API_KEY" \
-F "filter_by=qrid" \
-F "q=Qf94b25d768294148"
```
## Response
* **Status**: `200 OK` on success.
* **Content-Type**: Matches the requested format (`text/csv`, `application/vnd.ms-excel`, or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`).
* **Body**: Each row represents a scan with timestamp, device, OS, browser, geo metadata, campaign references, and any other available scan attributes.
Raw files can grow quickly when exporting long date ranges or busy campaigns. For >50k scans, schedule the job during off-hours or break the date range into weekly slices.
## Tips
* Pair this export with the aggregate `/analytics/qr/export/` report to validate funnel metrics.
* CSV output is best suited for ETL/ELT jobs and scripting workflows.
* XLS/XLSX provide richer formatting if you need to hand the dataset to stakeholders without additional tooling.
## OpenAPI
````yaml POST /analytics/qr/raw/
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/raw/:
post:
summary: Export raw analytics
description: >-
Exports raw, per-scan analytics records (one row per scan) as csv, xls,
or xlsx (no pdf). POST-only; shares its request body and volume-cap
validation with /analytics/qr/. Pass type=raw_bot as a query parameter
to export bot-only scan records instead of all scans.
operationId: exportManagedRawAnalytics
parameters:
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: file_format
in: query
required: true
schema:
type: string
enum:
- csv
- xls
- xlsx
- name: type
in: query
schema:
type: string
enum:
- raw_bot
description: >-
Pass raw_bot for a bot-only export; any other value is overwritten
to raw.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
q:
type: array
items:
type: string
filter_by:
type: string
enum:
- qrid
- tags
- id
- folder
default: qrid
required:
- q
example:
q:
- Q07afe81aa0034c01
filter_by: qrid
responses:
'200':
description: >-
Binary file download — text/csv for csv, spreadsheet mimetype for
xls/xlsx.
content:
text/csv: {}
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: {}
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.
````