Skip to content
FrameWorks Docs
Blog

Analytics API

The webapp’s /analytics, /analytics/audience, /analytics/usage, and /streams/:id/analytics pages are all built on the same GraphQL surface you can query directly. This page maps each view to the operations that drive it so you can replicate or extend them in your own dashboards.

Per-stream analytics

Section titled “Per-stream analytics”

The /streams/:id/analytics and /streams/:id/health views are powered by a single analytics query that aggregates current state and recent rollups for one stream.

query StreamAnalytics($streamId: ID!, $rangeStartMs: Int!, $rangeEndMs: Int!) {
  analytics(streamId: $streamId, rangeStartMs: $rangeStartMs, rangeEndMs: $rangeEndMs) {
    streamHealth {
      bitrateKbps
      framerate
      packetLossPct
      bufferHealth
    }
    viewerMetrics {
      currentViewers
      peakViewers
      bandwidthMbps
    }
    qualityTiers {
      tier
      currentViewers
    }
  }
}

For real-time updates, subscribe instead of polling:

subscription LiveHealth($streamId: ID!) {
  liveSystemHealth(streamId: $streamId) {
    timestamp
    bitrateKbps
    framerate
    packetLossPct
  }
}


subscription LiveViewers($streamId: ID!) {
  liveViewerMetrics(streamId: $streamId) {
    timestamp
    currentViewers
    bandwidthMbps
  }
}

Tenant-wide audience

Section titled “Tenant-wide audience”

/analytics/audience aggregates viewer counts, geographic distribution, and per-stream rankings across the whole tenant.

query Audience($rangeStartMs: Int!, $rangeEndMs: Int!) {
  analytics(rangeStartMs: $rangeStartMs, rangeEndMs: $rangeEndMs) {
    aggregateViewers {
      currentViewers
      peakViewers
      uniqueViewers
    }
    geographicBreakdown {
      country
      currentViewers
      bandwidthMbps
    }
  }
}

Tenant usage and billing

Section titled “Tenant usage and billing”

/analytics/usage and /account/billing share the usage surface. Use usageAggregates for the rolled-up summary or usageRecordsConnection for paginated raw records.

query Usage($rangeStartMs: Int!, $rangeEndMs: Int!) {
  usageAggregates(rangeStartMs: $rangeStartMs, rangeEndMs: $rangeEndMs) {
    transcodeMinutes
    deliveredMinutes
    storageGbDays
    bandwidthGb
  }
  tenantUsage {
    currentPeriod {
      transcodeMinutes
      deliveredMinutes
      storageGbDays
    }
  }
}


query DetailedUsage($page: ConnectionInput) {
  usageRecordsConnection(page: $page) {
    edges {
      node {
        timestamp
        usageType
        quantity
        unit
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Network and federation

Section titled “Network and federation”

/network and /infrastructure/federation show public platform topology and orchestrator vantage points across the federation. Authenticated users also see subscribed or owned clusters with cluster-level KPIs, plus tenant-scoped routing and federation overlays for their own streams.

query NetworkStatus {
  networkStatus {
    clusters {
      clusterId
      region
      activeStreams
      activeViewers
      capacityUtilization
    }
  }
  orchestratorVantages {
    orchestratorAddress
    vantagePoints {
      cluster
      latencyMs
    }
  }
}

Live event firehose

Section titled “Live event firehose”

For dashboards that want the raw event stream (every viewer connect/disconnect, every track change, every storage event), subscribe to the firehose. Be deliberate — this is high-volume.

subscription Firehose {
  liveFirehose {
    timestamp
    eventType
    payload
  }
}

Agents (MCP)

Section titled “Agents (MCP)”

Agents call analytics through diagnostic tools rather than direct GraphQL — see agents/mcp for get_stream_health_summary, get_anomaly_report, diagnose_buffer_health, diagnose_packet_loss, diagnose_rebuffering, and diagnose_routing. Each wraps one or more of the queries above with summarization tuned for agent consumption.

Section titled “Related”