Skip to content
API key

API reference

Analytics endpoints

Read scan totals, a daily timeline and, on plans that include them, country and device breakdowns.

Account scan statistics

GEThttps://api.qrbold.com/api/public/v1/analytics/overview Try it

Returns scan statistics for the whole account, with the five busiest codes in the period.

API key required. Scope: analytics:read. Campaign-scoped keys are refused. Plan: Pro, or the Business card plan.

Request

Request headers
HeaderRequiredValue
AuthorizationRequiredBearer YOUR_API_KEY. X-API-Key: YOUR_API_KEY is accepted instead.

Query parameters

Query parameters
NameTypeRequiredDescription
rangestringOptionalThe period to report. One of 7d, 30d, 90d, 12m. Default: 30d.
timeZonestringOptionalIANA time zone the daily buckets are cut in, e.g. Europe/London. Default: UTC.

Example request

curl "https://api.qrbold.com/api/public/v1/analytics/overview?range=30d&timeZone=Europe%2FLondon" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

Response

200 A scan_stats object with qrCodeId null and topQrCodes present.

200 response
{
  "object": "scan_stats",
  "qrCodeId": null,
  "range": "30d",
  "period": {
    "start": "2026-09-09T00:00:00.000Z",
    "end": "2026-10-09T09:40:00.000Z",
    "days": 30
  },
  "clamped": false,
  "historyDays": -1,
  "totalScans": 120,
  "uniqueVisitors": 80,
  "previousPeriodScans": 100,
  "trend": "+20%",
  "timeline": [
    {
      "date": "2026-10-07",
      "scans": 6
    },
    {
      "date": "2026-10-08",
      "scans": 9
    }
  ],
  "topCountries": [
    {
      "country": "United Kingdom",
      "code": "GB",
      "scans": 74
    }
  ],
  "devices": [
    {
      "device": "Mobile",
      "scans": 108,
      "percent": 90
    }
  ],
  "topQrCodes": [
    {
      "id": "cmf3k2a9x0001",
      "name": "Ada Lovelace",
      "type": "card",
      "scans": 74
    },
    {
      "id": "cmf3k4c2e0003",
      "name": "Spring menu",
      "type": "url",
      "scans": 46
    }
  ]
}

Errors

Errors specific to Account scan statistics
StatusCodeWhenRetry?
422validation_failedThe request body or the query string did not pass validation.Only after changing the request or the account

Every endpoint can also answer 401 invalid_api_key, 403 forbidden, 403 upgrade_required_api, 404 unknown_endpoint, 429 rate limited and 500 internal_error. One failing response is shown below.

422 response
{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "fields.links.0.type",
        "message": "Invalid enum value",
        "code": "invalid_enum_value"
      },
      {
        "field": "shortCode",
        "message": "Slugs can only contain letters, numbers, and hyphens",
        "code": "invalid_string"
      }
    ]
  }
}

Related

Scan statistics for one code or card

GEThttps://api.qrbold.com/api/public/v1/analytics/:id Try it

Returns scan statistics for a single QR code or digital business card.

API key required. Scope: analytics:read. Campaign-scoped keys are refused. Plan: Pro, or the Business card plan.

Request

Request headers
HeaderRequiredValue
AuthorizationRequiredBearer YOUR_API_KEY. X-API-Key: YOUR_API_KEY is accepted instead.
Path parameters
NameTypeRequiredDescription
idstringRequiredA QR code id or a card id.

Query parameters

Query parameters
NameTypeRequiredDescription
rangestringOptionalThe period to report. One of 7d, 30d, 90d, 12m. Default: 30d.
timeZonestringOptionalIANA time zone the daily buckets are cut in. Default: UTC.

Example request

curl "https://api.qrbold.com/api/public/v1/analytics/cmf3k2a9x0001?range=7d" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

Response

200 A scan_stats object.

200 response
{
  "object": "scan_stats",
  "qrCodeId": "cmf3k2a9x0001",
  "range": "30d",
  "period": {
    "start": "2026-09-09T00:00:00.000Z",
    "end": "2026-10-09T09:40:00.000Z",
    "days": 30
  },
  "clamped": false,
  "historyDays": -1,
  "totalScans": 120,
  "uniqueVisitors": 80,
  "previousPeriodScans": 100,
  "trend": "+20%",
  "timeline": [
    {
      "date": "2026-10-07",
      "scans": 6
    },
    {
      "date": "2026-10-08",
      "scans": 9
    }
  ],
  "topCountries": [
    {
      "country": "United Kingdom",
      "code": "GB",
      "scans": 74
    }
  ],
  "devices": [
    {
      "device": "Mobile",
      "scans": 108,
      "percent": 90
    }
  ]
}

Errors

Errors specific to Scan statistics for one code or card
StatusCodeWhenRetry?
422validation_failedThe request body or the query string did not pass validation.Only after changing the request or the account
404resource_not_foundNothing with that id exists in this account.No

Every endpoint can also answer 401 invalid_api_key, 403 forbidden, 403 upgrade_required_api, 404 unknown_endpoint, 429 rate limited and 500 internal_error. One failing response is shown below.

422 response
{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "fields.links.0.type",
        "message": "Invalid enum value",
        "code": "invalid_enum_value"
      },
      {
        "field": "shortCode",
        "message": "Slugs can only contain letters, numbers, and hyphens",
        "code": "invalid_string"
      }
    ]
  }
}

Related