Activity matrix

get/v1/stats/activity

This endpoint is in the contract, but the API doesn't serve it during early access. It returns 404 for now.

Per-entity daily activity matrix (heat-map), busiest first. Not cursor-paginated: capped by top. Only dimension=screen exists today; other dimensions may be added.

curl "https://api.vojo-media.com/v1/stats/activity" \
  -H "Authorization: Bearer $VOJO_KEY"

const { data, error } = await api.GET("/v1/stats/activity");
if (error) throw new VojoApiError(error);

Response 200

{
  "data": {
    "range": "7d",
    "dimension": "screen",
    "buckets": [
      "2026-10-06T00:00:00Z",
      "2026-10-07T00:00:00Z"
    ],
    "rows": [
      {
        "id": "cm1scr2w6n0001h8d4k9t3m7ve",
        "label": "Lobby North",
        "sub": "Leeds Trinity",
        "total": 1840,
        "cells": [
          {
            "bucket": "2026-10-06T00:00:00Z",
            "value": 1020,
            "status": "ok"
          },
          {
            "bucket": "2026-10-07T00:00:00Z",
            "value": 820,
            "status": "ok"
          }
        ]
      }
    ],
    "max": 1020
  },
  "meta": {
    "scope": {
      "type": "org",
      "id": null,
      "name": null
    },
    "generated_at": "2026-10-07T09:30:00Z"
  }
}

Access

Authentication: Secret key or OAuth access token.
Scope: stats:read
User permission: networkViewStats

Query parameters

rangestring
Window ending now.
One of 7d, 30d
Default "30d"
dimensionstring
Row entity.
One of screen
Default "screen"
topinteger
Maximum rows, busiest first.
1 to 100
Default 25
scope_typestring
Slice of the fleet to aggregate over. Default org.
One of org, site, screen, campaign
Default "org"
scope_idstring
Entity id for scope_type site / screen / campaign (required for those, ignored for org). Resolved server-side within the org: an id from another org yields an empty result, never a leak.

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
Vojo-Versionstring
Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.
date

Response 200

dataobjectRequired
Show 5 fields
- rangestringRequired
  One of 7d, 30d
- dimensionstringRequired
  One of screen
- bucketsarray of stringRequired
  Day-bucket starts, oldest first.
  each date-time
- rowsarray of objectsRequired
  Busiest first, capped by top.
  Show 5 fields
  - idstringRequired
    Row entity id. Opaque string — treat as an identifier, never parse it.
  - labelstringRequired
  - substring or nullRequired
    Secondary label (e.g. the site name).
  - totalintegerRequired
    at least 0
  - cellsarray of objectsRequired
    Show 3 fields
    bucketstringRequired
    RFC 3339 / ISO-8601 UTC timestamp.
    date-time
    valueintegerRequired
    at least 0
    statusstringRequired
    ok = evidence in this bucket; empty = none. Not a screen on/off state.
    One of ok, empty
- maxintegerRequired
  Peak cell value across the matrix.
  at least 0
metaobjectRequired
Metadata for aggregate reads.
Show 2 fields
- scopeobjectRequired
  The scope the aggregate was resolved to, echoed so callers need no extra lookup for a label.
  Show 3 fields
  - typestringRequired
    Slice of the fleet an aggregate is computed over.
    One of org, site, screen, campaign
  - idstring or nullRequired
    Entity id for site / screen / campaign scopes; null for org.
  - namestring or nullRequired
    Display name of the scoped entity; null for org.
- generated_atstringRequired
  When the aggregate was computed.
  date-time

Response headers

Vojo-Versionstring
The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.
RateLimitstring
IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.
RateLimit-Policystring
IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.

Errors

Every error is application/problem+json. Branch on its code.

400
Malformed request: invalid JSON, a bad cursor, a missing Vojo-Organisation for an OAuth caller, or an unknown Vojo-Version.
401
Missing, invalid, expired or revoked credential.
403
The caller is authenticated but not allowed: missing scope (insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied).
422
Well-formed request that failed validation. errors[] lists each failing field.
429
Rate limit exceeded for this principal. Back off for Retry-After seconds.
500
Unexpected server failure.