> ## 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.0.0
info:
title: Scanova API - Analytics
description: >-
Analytics endpoints for retrieving QR code scan data, statistics, and
exporting analytics reports. These endpoints provide comprehensive insights
into QR code performance, user behavior, and geographic distribution.
version: 1.0.0
servers:
- url: https://management.scanova.io
description: Scanova Management API Server
security:
- apiKeyAuth: []
paths:
/analytics/qr/raw/:
post:
tags:
- Analytics
summary: Export Raw Scan Data
description: >-
Download raw (row-level) scan logs for one or more QR codes within a
specified date range. Use this endpoint when you need the underlying
scan events rather than the aggregated analytics report.
parameters:
- name: type
in: query
required: true
description: Must be set to `raw` to retrieve raw scan data.
schema:
type: string
enum:
- raw
example: raw
- name: from
in: query
required: true
description: 'Start date for scan data (inclusive). Format: YYYY-MM-DD'
schema:
type: string
format: date
example: '2025-10-28'
- name: to
in: query
required: true
description: >-
End date for scan data (inclusive). Format: YYYY-MM-DD. Defaults to
current date.
schema:
type: string
format: date
example: '2025-11-26'
- name: file_format
in: query
required: true
description: >-
Export file format for the raw data. CSV is ideal for lightweight
processing.
schema:
type: string
enum:
- csv
- xls
- xlsx
example: csv
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- filter_by
- q
properties:
filter_by:
type: string
enum:
- qrid
- tags
description: Filter by QR code ID or tags
example: qrid
q:
type: array
items:
type: string
description: >-
Array of QR code IDs (if filter_by is 'qrid') or tags (if
filter_by is 'tags') to include in the raw export
example:
- Qf94b25d768294148
- Qf94b25d768294149
examples:
raw_by_qr_ids:
summary: Export raw scan data for specific QR IDs
value:
filter_by: qrid
q:
- Qf94b25d768294148
- Qf94b25d768294149
raw_by_tags:
summary: Export raw scan data by tags
value:
filter_by: tags
q:
- marketing
- campaign
responses:
'200':
description: Raw scan data exported successfully
content:
text/csv:
schema:
type: string
format: binary
application/vnd.ms-excel:
schema:
type: string
format: binary
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
schema:
type: string
format: binary
'400':
description: Bad request - Invalid parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid parameters
message:
type: string
example: Required parameters are missing or invalid
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: Authentication credentials were not provided.
security:
- apiKeyAuth: []
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
API key authentication. Enter your API key directly in the Authorization
header.
````