Skip to content
FrameWorks Docs
Blog

Clusters and infrastructure types

GraphQL schema reference · API guide · SDKs · Types of Clusters and infrastructure

AvailableCluster

Section titled “AvailableCluster”

object

  • clusterId: String!
  • clusterName: String!
  • tiers: [String!]!
  • autoEnroll: Boolean!

AvailableClusterConnection

Section titled “AvailableClusterConnection”

object

AvailableClusterEdge

Section titled “AvailableClusterEdge”

object

BootstrapEdgeInput

Section titled “BootstrapEdgeInput”

input_object

  • token: String! — Bootstrap token issued by createEdgeCluster or createEnrollmentToken.
  • externalIp: String — External IP of the edge being bootstrapped (helps Foghorn assign a domain).
  • preferredNodeId: String — Caller-supplied node id hint; Foghorn may ignore.

BootstrapEdgeResponse

Section titled “BootstrapEdgeResponse”

object

Result of a successful bootstrapEdge call. Carries everything the edge needs to come online: its identity, its assigned Foghorn for runtime traffic, and (if the cluster issues per-node certs) its initial TLS material plus the cluster’s internal CA bundle.

  • nodeId: String!
  • edgeDomain: String!
  • poolDomain: String
  • clusterSlug: String!
  • clusterId: String!
  • foghornGrpcAddr: String!
  • certPem: String
  • keyPem: String
  • internalCaBundle: String
  • telemetry: EdgeTelemetrySetup (EdgeTelemetrySetup)

BootstrapEdgeResult

Section titled “BootstrapEdgeResult”

union

BootstrapToken

Section titled “BootstrapToken”

object

A bootstrap token for provisioning new infrastructure nodes. Used during initial node registration to authenticate join requests.

  • id: ID! — Unique token identifier.
  • name: String! — Human-readable name for the token.
  • token: String — The secret token value (only returned on creation).
  • kind: String! — Token type (edge_node, service).
  • clusterId: String — Target cluster UUID for node tokens (not the Relay ID).
  • expectedIp: String — Expected IP address for validation.
  • metadata: JSON (JSON) — Additional metadata for the token.
  • usageLimit: Int — Maximum number of times this token can be used.
  • usageCount: Int! — Number of times this token has been used.
  • expiresAt: Time (Time) — When the token expires.
  • usedAt: Time (Time) — When the token was last used.
  • createdBy: String — User who created the token.
  • createdAt: Time! (Time) — When the token was created.

Cluster

Section titled “Cluster”

object

A streaming cluster containing one or more infrastructure nodes. Clusters provide isolated capacity for streaming workloads.

Implements Node.

  • id: ID! — Global unique identifier for Relay compatibility.
  • clusterId: String! — Internal cluster identifier (UUID).
  • clusterName: String! — Human-readable cluster name.
  • clusterType: String! — Cluster architecture type (dedicated, shared, hybrid).
  • deploymentModel: String! — Deployment model (platform, private, hybrid).
  • baseUrl: String! — Base URL for cluster API access.
  • databaseUrl: String — Internal database connection URL.
  • periscopeUrl: String — Analytics query endpoint URL.
  • kafkaBrokers: [String!] — Kafka broker addresses for event streaming.
  • maxConcurrentStreams: Int! — Maximum allowed concurrent streams.
  • maxConcurrentViewers: Int! — Maximum allowed concurrent viewers.
  • maxBandwidthMbps: Int! — Maximum allowed bandwidth in Mbps.
  • healthStatus: String! — Cluster health status (healthy, degraded, critical).
  • isActive: Boolean! — Whether the cluster is operational.
  • isDefaultCluster: Boolean! — Whether this is the tenant’s default cluster.
  • isPlatformOfficial: Boolean! — Whether this cluster is a platform-official regional/control cell.
  • regionId: String — Operational region identifier for this cluster.
  • isSubscribed: Boolean! — Whether the current tenant is subscribed.
  • createdAt: Time (Time) — When the cluster was created.
  • updatedAt: Time (Time) — When the cluster was last updated.
  • ownerTenantId: ID — Tenant that owns this cluster (for private clusters).
  • visibility: ClusterVisibility! (ClusterVisibility) — Marketplace visibility (PUBLIC, PRIVATE, INVITE_ONLY).
  • pricingModel: ClusterPricingModel! (ClusterPricingModel) — Pricing model for subscriptions.
  • monthlyPriceCents: Int — Monthly subscription price in cents.
  • requiresApproval: Boolean! — Whether access requires owner approval.
  • shortDescription: String — Short marketplace description.
  • nodesConnection: NodesConnection (NodesConnection) — Paginated list of nodes in this cluster.

ClusterAccess

Section titled “ClusterAccess”

object

  • clusterId: String!
  • clusterName: String!
  • accessLevel: String!
  • resourceLimits: JSON (JSON)
  • allowPrivatePullSources: Boolean! — Whether the cluster may pull from private (RFC 1918) and multicast sources.

ClusterAccessConnection

Section titled “ClusterAccessConnection”

object

ClusterAccessEdge

Section titled “ClusterAccessEdge”

object

ClusterEdge

Section titled “ClusterEdge”

object

  • cursor: String!
  • node: Cluster! (Cluster)

ClusterInvite

Section titled “ClusterInvite”

object

  • id: ID!
  • clusterId: String!
  • invitedTenantId: ID!
  • inviteToken: String
  • accessLevel: String!
  • resourceLimits: JSON (JSON)
  • status: String!
  • createdBy: ID!
  • createdAt: Time! (Time)
  • expiresAt: Time (Time)
  • acceptedAt: Time (Time)
  • invitedTenantName: String
  • clusterName: String

ClusterInviteConnection

Section titled “ClusterInviteConnection”

object

ClusterInviteEdge

Section titled “ClusterInviteEdge”

object

ClusterPricingModel

Section titled “ClusterPricingModel”

enum

  • FREE_UNMETERED
  • METERED
  • MONTHLY
  • TIER_INHERIT
  • CUSTOM

ClusterSubscription

Section titled “ClusterSubscription”

object

  • id: ID!
  • tenantId: ID!
  • clusterId: String!
  • accessLevel: String!
  • subscriptionStatus: ClusterSubscriptionStatus! (ClusterSubscriptionStatus)
  • resourceLimits: JSON (JSON)
  • requestedAt: Time (Time)
  • approvedAt: Time (Time)
  • approvedBy: ID
  • rejectionReason: String
  • expiresAt: Time (Time)
  • createdAt: Time! (Time)
  • updatedAt: Time! (Time)
  • clusterName: String
  • tenantName: String

ClusterSubscriptionConnection

Section titled “ClusterSubscriptionConnection”

object

ClusterSubscriptionEdge

Section titled “ClusterSubscriptionEdge”

object

ClusterSubscriptionResult

Section titled “ClusterSubscriptionResult”

union

ClusterSubscriptionStatus

Section titled “ClusterSubscriptionStatus”

enum

  • PENDING_APPROVAL
  • ACTIVE
  • SUSPENDED
  • REJECTED

ClusterVisibility

Section titled “ClusterVisibility”

enum

  • PUBLIC
  • UNLISTED
  • PRIVATE

ClustersConnection

Section titled “ClustersConnection”

object

CreateClusterInviteInput

Section titled “CreateClusterInviteInput”

input_object

Input for creating a cluster access invite.

  • clusterId: ID! — Target cluster ID.
  • invitedTenantId: ID! — Tenant to invite.
  • accessLevel: String — Access level (read, write, admin).
  • resourceLimits: JSON (JSON) — Resource limits for the invited tenant.
  • expiresInDays: Int — Days until invite expires.

CreateClusterInviteResult

Section titled “CreateClusterInviteResult”

union

CreateEdgeClusterInput

Section titled “CreateEdgeClusterInput”

input_object

  • clusterName: String! — Human-readable cluster name.
  • shortDescription: String — Short description.
  • controlClusterId: ID — Optional platform-official cluster/cell to control this edge cluster.

CreateEdgeClusterResponse

Section titled “CreateEdgeClusterResponse”

object

CreateEdgeClusterResult

Section titled “CreateEdgeClusterResult”

union

CreateEnrollmentTokenResponse

Section titled “CreateEnrollmentTokenResponse”

object

CreateEnrollmentTokenResult

Section titled “CreateEnrollmentTokenResult”

union

EdgeTelemetrySetup

Section titled “EdgeTelemetrySetup”

object

  • enabled: Boolean!
  • writeUrl: String
  • bearerToken: String

InfrastructureNode

Section titled “InfrastructureNode”

object

An infrastructure node in a cluster (edge server, origin, transcoder). Nodes handle stream ingest, transcoding, and delivery to viewers.

Implements Node.

  • id: ID! — Global unique identifier for Relay compatibility.
  • nodeId: String! — Internal node identifier (UUID).
  • clusterId: String! — Cluster this node belongs to.
  • nodeName: String! — Human-readable node name.
  • nodeType: String! — Node role (edge, origin, transcoder, hybrid).
  • internalIp: String — Private network IP address.
  • externalIp: String — Public IP address for external access.
  • wireguardIp: String — WireGuard mesh network IP.
  • wireguardPublicKey: String — WireGuard public key for mesh peering.
  • region: String — Geographic region (us-east, eu-west, etc.).
  • latitude: Float — GPS latitude.
  • longitude: Float — GPS longitude.
  • availabilityZone: String — Availability zone within region.
  • cpuCores: Int — Number of CPU cores.
  • memoryGb: Int — Memory in gigabytes.
  • diskGb: Int — Disk storage in gigabytes.
  • lastHeartbeat: Time (Time) — Last heartbeat timestamp from node agent.
  • tags: JSON (JSON) — Custom tags for node organization.
  • metadata: JSON (JSON) — Additional node metadata.
  • createdAt: Time (Time) — When the node was registered.
  • updatedAt: Time (Time) — When the node was last updated.
  • metricsConnection: NodeMetricsConnection! (NodeMetricsConnection) — Paginated time-series metrics for this node.
  • metrics1hConnection: NodeMetrics1hConnection! (NodeMetrics1hConnection) — Hourly aggregated metrics for this node.
  • liveState: LiveNode (LiveNode) — Real-time state from the analytics data plane.
  • effectiveMode: NodeOperationalMode! (NodeOperationalMode) — Current operational mode (normal / draining / maintenance). Read from Foghorn’s per-node heartbeat. Changes via setNodeMode.
  • routingImpactPreview: RoutingImpactPreview! (RoutingImpactPreview) — Current traffic on this node. Operators use these counts to understand how much live traffic is affected before draining or entering maintenance. Counts come from Foghorn’s GetNodeHealth.

LiveNode

Section titled “LiveNode”

object

  • nodeId: String!
  • tenantId: ID!
  • cpuPercent: Float!
  • ramUsedBytes: Float! — Used memory in MiB (field name is historical).
  • ramTotalBytes: Float! — Total memory in MiB (field name is historical).
  • diskUsedBytes: Float!
  • diskTotalBytes: Float!
  • upSpeed: Float!
  • downSpeed: Float!
  • activeStreams: Int!
  • isHealthy: Boolean!
  • latitude: Float!
  • longitude: Float!
  • location: String!
  • metadata: JSON (JSON)
  • updatedAt: Time! (Time)

MarketplaceCluster

Section titled “MarketplaceCluster”

object

  • clusterId: String!
  • clusterName: String!
  • shortDescription: String
  • visibility: ClusterVisibility! (ClusterVisibility)
  • pricingModel: ClusterPricingModel! (ClusterPricingModel)
  • monthlyPriceCents: Int
  • requiresApproval: Boolean!
  • ownerName: String
  • maxConcurrentStreams: Int!
  • maxConcurrentViewers: Int!
  • currentUtilization: Float
  • isSubscribed: Boolean!
  • subscriptionStatus: ClusterSubscriptionStatus (ClusterSubscriptionStatus)
  • isEligible: Boolean! — Whether the tenant can subscribe based on billing tier.
  • denialReason: String — Generic reason if the tenant is not eligible.

MarketplaceClusterConnection

Section titled “MarketplaceClusterConnection”

object

MarketplaceClusterEdge

Section titled “MarketplaceClusterEdge”

object

MistAdminSession

Section titled “MistAdminSession”

object

Short-lived credentials that let an authorized operator open the MistServer admin UI on a specific edge node. The webapp POSTs sessionToken (in the form body, NOT a query string) to postUrl. Helmsman validates the token against Foghorn, sets an HttpOnly, Secure, SameSite=Lax cookie scoped to Path=/_mist, and redirects the browser to /_mist/ where the LSP UI loads. sessionToken is bound to one nodeId via the JWT’s node_id claim; replay against any other edge node fails. expiresAt is Unix seconds.

  • postUrl: String! — Per-edge URL to POST the session token to (e.g. https://edge-us-1.media-us-1.frameworks.network/_mist-session).
  • sessionToken: String! — Short-TTL JWT to submit as the session_token form field. Treat as a secret.
  • expiresAt: Int! — Unix-seconds expiry of the token. The webapp can refuse to open if already past.

MySubscriptionEdge

Section titled “MySubscriptionEdge”

object

  • cursor: String!
  • node: Cluster! (Cluster)

MySubscriptionsConnection

Section titled “MySubscriptionsConnection”

object

NodeEdge

Section titled “NodeEdge”

object

NodeOperationalMode

Section titled “NodeOperationalMode”

enum

Operational mode controlling whether a node accepts new sessions. The mode is set via setNodeMode and snapshotted onto the node’s heartbeat; routing inspects it via GetNodeHealth and steers around drained / maintenance nodes.

  • NORMAL — Accepts new viewers and ingest. Default.
  • DRAINING — Existing viewers continue; new viewers are routed elsewhere. Use before maintenance to bleed load gracefully.
  • MAINTENANCE — Hard out — node is removed from routing entirely. Existing sessions terminate.

NodesConnection

Section titled “NodesConnection”

object

OpenMistAdminSessionInput

Section titled “OpenMistAdminSessionInput”

input_object

  • nodeId: ID! — Node identifier — accepts the InfrastructureNode.id (Relay global) or nodeId (raw UUID).

OpenMistAdminSessionResult

Section titled “OpenMistAdminSessionResult”

union

Orchestrator

Section titled “Orchestrator”

object

Identity-level orchestrator row — keyed by eth address. An orchestrator typically fronts N instances behind a load-balanced DNS hostname; per-instance config (price, capabilities, hardware) lives on OrchestratorInstance and can legitimately differ across instances even under the same eth address.

  • tenantId: ID!
  • orchAddr: String!
  • lastSeen: Time! (Time)
  • updatedAt: Time! (Time)

OrchestratorCapabilityPrice

Section titled “OrchestratorCapabilityPrice”

object

One per-capability price entry. The gateway emits these as typed OrchestratorCapabilityPriceEntry proto messages; if capability is empty it falls back to pos:<N> reflecting the index in upstream’s capabilities_prices array. Prices are exposed as ETH-denominated decimal strings so clients never handle wei-scale integers through JSON floats.

  • capability: String!
  • pricePerUnitEth: String!
  • pixelsPerUnit: String!

OrchestratorInstance

Section titled “OrchestratorInstance”

object

Per-instance state. One per (tenant, orch_addr, resolved_ip). Multiple instances of the same orch can have independent prices, capabilities, and hardware — the side panel renders this list so divergence is visible.

  • tenantId: ID!
  • orchAddr: String!
  • resolvedIp: String!
  • canonicalUrl: String!
  • advertisedNodeUrls: [String!]!
  • capabilities: [String!]!
  • pricePerUnitEth: String!
  • pixelsPerUnit: String!
  • capabilityPrices: [OrchestratorCapabilityPrice!]! (OrchestratorCapabilityPrice)
  • hardware: String!
  • source: String!
  • lastSeen: Time! (Time)
  • updatedAt: Time! (Time)

OrchestratorPerformancePoint

Section titled “OrchestratorPerformancePoint”

object

One sample from discovery and outcome rollups. Discovery metrics are per-vantage; transcode and AI outcome metrics are keyed by the gateway and the resolved instance IP observed by the gateway.

  • timestamp: Time! (Time)
  • gatewayId: String!
  • gatewayRegion: String!
  • resolvedIp: String!
  • attempts: Float!
  • successes: Float!
  • failures: Float!
  • meanLatencyMs: Float!
  • maxLatencyMs: Int!
  • transcodeAttempts: Float!
  • transcodeSuccesses: Float!
  • transcodeFailures: Float!
  • transcodeMeanOverallMs: Float!
  • transcodeMaxOverallMs: Int!
  • transcodePixels: Float!
  • aiAttempts: Float!
  • aiSuccesses: Float!
  • aiFailures: Float!
  • aiMeanLatencyMs: Float!
  • aiMaxLatencyMs: Int!

OrchestratorVantage

Section titled “OrchestratorVantage”

object

Per-vantage observation: one row per (cluster owner tenant, gateway, orch address, resolved IP). DNS round-robin / geo-anycast surfaces as multiple vantages with different resolvedIp.

  • tenantId: ID!
  • gatewayId: String!
  • gatewayRegion: String!
  • orchAddr: String!
  • resolvedIp: String!
  • latitude: Float!
  • longitude: Float!
  • city: String!
  • countryCode: String!
  • geoSource: String!
  • geoResolvedAt: Time (Time) — When the vantage’s location was resolved; null while it has not been.
  • latestLatencyMs: Int!
  • score: Float!
  • dialedRecently: Boolean!
  • lastSeen: Time! (Time)

OrchestratorWithDetails

Section titled “OrchestratorWithDetails”

object

Detail response: orchestrator identity + every known instance (with their own price/capabilities/hardware) + every per-(gateway, instance) vantage. Used by the federation map’s side panel.

OrchestratorsConnection

Section titled “OrchestratorsConnection”

object

Pagination wrapper for orchestrator listing.

RevokeClusterInviteResult

Section titled “RevokeClusterInviteResult”

union

RoutingImpactPreview

Section titled “RoutingImpactPreview”

object

Snapshot of how much traffic a node is currently serving.

  • activeStreams: Int!
  • activeViewers: Int!

SetNodeModeInput

Section titled “SetNodeModeInput”

input_object

  • nodeId: ID! — Node identifier — accepts the InfrastructureNode.id (Relay global) or nodeId (raw UUID).
  • mode: NodeOperationalMode! (NodeOperationalMode)
  • reason: String — Free-text reason recorded in Foghorn’s audit trail. Defaults to the calling user/agent identity.

SetNodeModeResult

Section titled “SetNodeModeResult”

union

SetPreferredClusterResult

Section titled “SetPreferredClusterResult”

union

UpdateClusterMarketplaceInput

Section titled “UpdateClusterMarketplaceInput”

input_object

Input for updating cluster marketplace settings.

  • visibility: ClusterVisibility (ClusterVisibility) — Marketplace visibility (PUBLIC, UNLISTED, PRIVATE).
  • pricingModel: ClusterPricingModel (ClusterPricingModel) — Pricing model for subscriptions.
  • monthlyPriceCents: Int — Monthly subscription price in cents.
  • requiresApproval: Boolean — Whether access requires owner approval.
  • shortDescription: String — Short marketplace description.

UpdateClusterResult

Section titled “UpdateClusterResult”

union