Core Resource • Privacy-Preserving Scan Telemetry

Scan Analytics API Reference

Access real-time scan metrics, 30-day time-series telemetry, device categories, OS distributions, city rollups, and privacy-preserving CSV/JSON data exports.

DPDP Act 2023 & GDPR Privacy Compliance

In strict compliance with privacy regulations, QRnaly never persists raw end-user IP addresses. Every incoming scan generates an irreversible SHA-256 salted hash (ip_hash). This guarantees accurate unique scan calculations without storing personally identifiable information (PII).

GET/api/v1/analytics/workspace

Workspace Aggregate Analytics

Aggregates scan telemetry across all active and paused campaigns in the workspace.

Authentication: Bearer Token / x-api-key

Required Scope: analytics:read

Query Parameters: days (optional, default: 30)

curl -X GET "https://qrnaly.com/api/v1/analytics/workspace?days=30" \
  -H "Authorization: Bearer qrs_live_your_api_key_here"

GET/api/v1/analytics/folders/:id

Folder Aggregate Analytics

Rolls up scan metrics for all QR codes contained within a specific campaign folder.

Authentication: Bearer Token / x-api-key

Required Scope: analytics:read

Parameters: :id (Folder ID)

curl -X GET "https://qrnaly.com/api/v1/analytics/folders/fol_01j8m2?days=30" \
  -H "Authorization: Bearer qrs_live_your_api_key_here"

GET/api/v1/analytics/:id

Single QR Scan Analytics

Returns comprehensive scan counts, daily time series, and device/location breakdowns for one QR code.

curl -X GET "https://qrnaly.com/api/v1/analytics/qr_01j8m4k8" \
  -H "Authorization: Bearer qrs_live_your_api_key_here"

Response Payload Example (HTTP 200)

{
  "data": {
    "qrId": "qr_01j8m4k8",
    "slug": "summer-festival",
    "metrics": {
      "totalScans": 1420,
      "uniqueScans": 980,
      "scansToday": 45,
      "scansThisMonth": 680,
      "latestScan": "2026-10-06T09:42:15.000Z"
    },
    "timeSeries": [
      { "date": "Oct 1", "day": "2026-10-01", "totalScans": 38, "uniqueScans": 29 },
      { "date": "Oct 2", "day": "2026-10-02", "totalScans": 52, "uniqueScans": 41 }
    ],
    "breakdowns": {
      "devices": [{ "name": "Mobile", "count": 1350, "percent": 95.1 }],
      "os": [{ "name": "iOS", "count": 820, "percent": 57.7 }, { "name": "Android", "count": 530, "percent": 37.3 }],
      "cities": [{ "name": "Mumbai", "count": 640, "percent": 45.1 }]
    }
  }
}

GET/api/v1/analytics/:id/export

Export Raw Scan Telemetry (CSV / JSON)

Stream privacy-preserving scan records with timestamp, country, city, device category, and salted IP hash.

Authentication: Bearer Token / x-api-key

Required Scope: analytics:read

Query Parameters: format=csv|json, limit=1000

curl -X GET "https://qrnaly.com/api/v1/analytics/qr_01j8m4k8/export?format=csv&limit=1000" \
  -H "Authorization: Bearer qrs_live_your_api_key_here"