Topolo Docs Topolo Platform
Open workspace

Get scan analytics

Returns scan counters for the selected code or workspace. These counters are read from the configured scan-count store, separately from daily rollups.

Outcome

Returns scan counters for the selected code or workspace. These counters are read from the configured scan-count store, separately from daily rollups.

Before you start

  • Verify identity, environment and the intended organization before discovery.
  • Discover the published analytics:read permission and the target policy.
  • Select an accessible canonical Auth workspace and set WORKSPACE_ID to its returned id. Workspace binding is separate from input.

Discover the target

topolo whoami --json
topolo workspaces list topolo-quro --json
topolo actions get app_topolo_quro.analytics.get --detail --json
  • quro_id: Discovered numeric code id for the analytics filter; retain the selected workspace binding separately.

Request

GET /analytics

Inspect parameters and test this action.

Input fields

FieldRequiredMeaning
quro_idNoDiscovered numeric code id for the analytics filter; retain the selected workspace binding separately.
slugNoExact requested or discovered QR slug. Slugs are globally unique; changing one can break distributed printed codes.
periodNoDeclared premium analytics window: day, week, month or year. The slug-only and workspace-counter branches return lifetime counters instead; inspect the response shape.

Worked examples

Actual exported Quro Worker with local Miniflare D1/KV and every committed app/analytics migration. Auth, service tokens, Nexus, destination probes and platform archival are synthetic responses; outbound fetch is sealed. Notifications remain in the local outbox. No live redirect propagation, QR scan, destination health, provider delivery, archival or production erasure is established.

Save reviewed input as payload.json, replacing fixture identifiers through discovery.

topolo actions validate app_topolo_quro.analytics.get --data @payload.json --json
topolo actions plan app_topolo_quro.analytics.get --resource-type workspace --resource-id "$WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_quro.analytics.get --resource-type workspace --resource-id "$WORKSPACE_ID" --data @payload.json --detail --json

MCP uses the same reviewed input and separately discovered resource binding:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_quro.analytics.get",
    "input": {
      "quro_id": 14,
      "period": "day"
    },
    "resourceType": "workspace",
    "resourceId": "ws_quro_fixture"
  }
}

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_quro.analytics.get",
    "input": {
      "quro_id": 14,
      "period": "day"
    },
    "resourceType": "workspace",
    "resourceId": "ws_quro_fixture",
    "detail": true
  }
}

Worked response 1 · HTTP 200 · Premium day breakdown

Input · payload.json:

{
  "quro_id": 14,
  "period": "day"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "quro_id": "14",
    "total_scans": 2,
    "period_scans": 2,
    "breakdown": [
      {
        "date": "2026-10-06",
        "scans": 2,
        "country": "GB",
        "device": "desktop",
        "browser": "fixture"
      }
    ],
    "tier": "premium"
  }
}

HTTP 200. Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Worked response 2 · HTTP 200 · Premium week breakdown

Input · payload.json:

{
  "quro_id": 14,
  "period": "week"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "quro_id": "14",
    "total_scans": 2,
    "period_scans": 2,
    "breakdown": [
      {
        "date": "2026-10-06",
        "scans": 2,
        "country": "GB",
        "device": "desktop",
        "browser": "fixture"
      }
    ],
    "tier": "premium"
  }
}

HTTP 200. Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Worked response 3 · HTTP 200 · Premium month breakdown

Input · payload.json:

{
  "quro_id": 14,
  "period": "month"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "quro_id": "14",
    "total_scans": 2,
    "period_scans": 2,
    "breakdown": [
      {
        "date": "2026-10-06",
        "scans": 2,
        "country": "GB",
        "device": "desktop",
        "browser": "fixture"
      }
    ],
    "tier": "premium"
  }
}

HTTP 200. Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Worked response 4 · HTTP 200 · Premium year breakdown

Input · payload.json:

{
  "quro_id": 14,
  "period": "year"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "quro_id": "14",
    "total_scans": 2,
    "period_scans": 2,
    "breakdown": [
      {
        "date": "2026-10-06",
        "scans": 2,
        "country": "GB",
        "device": "desktop",
        "browser": "fixture"
      }
    ],
    "tier": "premium"
  }
}

HTTP 200. Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Worked response 5 · HTTP 200 · Selected code

Input · payload.json:

{
  "quro_id": 1
}

Captured SDK response:

{
  "success": true,
  "data": {
    "quro_id": "1",
    "total_scans": 0,
    "tier": "standard"
  }
}

HTTP 200. Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Worked response 6 · HTTP 200 · Selected code

Input · payload.json:

{
  "slug": "premium-fixture"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "quro_id": 14,
    "slug": "premium-fixture",
    "total_scans": 2,
    "tier": "premium"
  }
}

HTTP 200. Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Worked response 7 · HTTP 404 · QURO code not found

Input · payload.json:

{
  "slug": "missing-fixture"
}

Captured SDK response:

{
  "success": false,
  "error": "QURO code not found"
}

HTTP 404. Discover the exact record id or slug in the same workspace before retrying.

Worked response 8 · HTTP 404 · QURO code not found

Input · payload.json:

{
  "quro_id": 999999
}

Captured SDK response:

{
  "success": false,
  "error": "QURO code not found"
}

HTTP 404. Discover the exact record id or slug in the same workspace before retrying.

Worked response 9 · HTTP 200 · Workspace scan counters

Input · payload.json:

{}

Captured SDK response:

{
  "success": true,
  "data": {
    "quro_codes": [
      {
        "id": 1,
        "slug": "quro-fixture",
        "url": "https://example.com/updated",
        "tier": "standard",
        "scans": 3
      },
      {
        "id": 2,
        "slug": "fixture-001",
        "url": "https://example.com/item/1",
        "tier": "basic",
        "scans": 0
      },
      {
        "id": 3,
        "slug": "fixture-002",
        "url": "https://example.com/item/2",
        "tier": "basic",
        "scans": 0
      },
      {
        "id": 4,
        "slug": "fixture-collision",
        "url": "https://example.com/collision/1",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 5,
        "slug": "fixture-collision-1",
        "url": "https://example.com/collision/2",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 6,
        "slug": "fixture-collision-2",
        "url": "https://example.com/collision/3",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 7,
        "slug": "fixture-collision-3",
        "url": "https://example.com/collision/4",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 8,
        "slug": "fixture-collision-4",
        "url": "https://example.com/collision/5",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 9,
        "slug": "fixture-collision-5",
        "url": "https://example.com/collision/6",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 10,
        "slug": "fixture-collision-6",
        "url": "https://example.com/collision/7",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 11,
        "slug": "fixture-collision-7",
        "url": "https://example.com/collision/8",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 12,
        "slug": "fixture-collision-8",
        "url": "https://example.com/collision/9",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 13,
        "slug": "fixture-collision-9",
        "url": "https://example.com/collision/10",
        "tier": "standard",
        "scans": 0
      },
      {
        "id": 14,
        "slug": "premium-fixture",
        "url": "https://example.com/item/premium",
        "tier": "premium",
        "scans": 2
      },
      {
        "id": 16,
        "slug": "6df2of7g",
        "url": "mailto:reviewed@example.com",
        "tier": "standard",
        "scans": 0
      }
    ],
    "total_scans": 5
  }
}

HTTP 200. Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Verify the result

  • Confirm the requested slug and tier or returned code inventory. Counter reads and rollup windows can differ; compare their declared sources rather than assuming identical totals.

Errors and recovery

  • HTTP 404 · http_error: Discover the exact record id or slug in the same workspace before retrying.
  • HTTP 401 · auth_error: Authenticate again in the intended environment and organization.
  • HTTP 403 · action_permission_required: Inspect the actual refusal. The action permission and the verified workspace access are both required; a caller cannot name an ungranted workspace.

Inspect the original handler body as well as the SDK error code. These are observed local refusals, not an exhaustive provider-failure list.

Recovery boundary

Read again after fixing authorization or unavailable storage; the operation does not alter a code.

Evidence

Actual exported Quro Worker with local Miniflare D1/KV and every committed app/analytics migration. Auth, service tokens, Nexus, destination probes and platform archival are synthetic responses; outbound fetch is sealed. Notifications remain in the local outbox. No live redirect propagation, QR scan, destination health, provider delivery, archival or production erasure is established.