Shared types

GraphQL schema reference · API guide · SDKs

Types that root fields of two or more domains reach: scalars, errors, pagination, and the core objects the domains have in common.

Types

AuthError

object

Implements Error.

• message: String!
• code: String

Clip

object

A video clip extracted from a live stream’s DVR buffer. Clips are created from recorded stream segments and stored for playback.

Implements Node.

• id: ID! — Global unique identifier for Relay compatibility.
• clipHash: String! — Internal clip hash for storage and playback.
• playbackId: String! — Public playback identifier for generating playback URLs.
• streamId: ID! — Stream this clip was created from.
• sourceStreamId: String! — Stable UUID of the source stream this clip was created from.
• stream: Stream (Stream)
• title: String! — Display title for the clip.
• description: String — Optional description of clip content.
• startTime: Int! — Resolved start time (Unix seconds).
• duration: Int! — Clip duration in seconds.
• nodeId: String — Node that processed this clip.
• storagePath: String — Storage path on the processing node.
• sizeBytes: Float — File size in bytes.
• status: String! — Processing status (queued, processing, ready, failed).
• createdAt: Time (Time) — When the clip was requested.
• updatedAt: Time (Time) — When the clip was last updated.
• clipMode: String — Clip creation mode (ABSOLUTE, RELATIVE, DURATION, CLIP_NOW).
• requestedParams: JSON (JSON) — Original request parameters for audit/display.
• storageLocation: String — Storage backend (local, s3).
• syncStatus: String — Current S3 sync state (pending, in_progress, synced, failed, lost_local).
• hasLocalCopy: Boolean — Present full local node copy (origin or cache): true when at least one node holds a complete local copy, false when none remain (playback via read-through relay from S3). Null when the placement overlay (Periscope) is unavailable — unknown, not ‘no local copy’. Durable S3-only state is derived by consumers as isSynced && hasLocalCopy == false.
• isSynced: Boolean — True when S3 has an authoritative copy.
• isFinalized: Boolean — True when the S3 copy includes the Mist .dtsh index.
• expiresAt: Time (Time) — When the clip will be auto-deleted.
• isExpired: Boolean! — Whether the clip has passed its retention date (expiresAt < now).
• playbackPolicy: PlaybackPolicy (PlaybackPolicy) — Playback access policy snapshotted at clip creation. null/PUBLIC means anyone with the playbackId can watch. Independent from the source stream’s policy after creation — flipping the source stream’s policy does not affect already-shared clip URLs.
• thumbnailAssets: ThumbnailAssets (ThumbnailAssets) — Server-resolved Chandler URLs for the clip’s poster and sprite thumbnails. Null until Foghorn confirms the thumbnail upload.
• effectiveRetention: EffectiveRetention (EffectiveRetention) — Resolved retention horizon with the source of the decision (per-asset override → per-stream override → tenant default → tier entitlement). Null when retention_until is unset (infinite).
• storageCost: StorageCostProjection (StorageCostProjection) — Marginal storage cost for this clip on the tenant’s tier. Null when the tenant has no storage meter (self-hosted, fully tenant-private cluster). Computed from sizeBytes in GiB × the tier’s price per GiB-month.

ConnectionEvent

object

Implements Node.

• id: ID!
• eventId: String!
• timestamp: Time! (Time)
• streamId: ID!
• stream: Stream (Stream)
• sessionId: String!
• connectionAddr: String
• connector: String!
• nodeId: String!
• countryCode: String
• city: String
• latitude: Float
• longitude: Float
• clientBucket: GeoBucket (GeoBucket)
• nodeBucket: GeoBucket (GeoBucket)
• eventType: String!
• requestUrl: String
• clusterId: String!
• originClusterId: String
• controlCellId: String
• sessionDurationSeconds: Int
• bytesTransferred: Float

ConnectionInput

input_object

Standard cursor-based pagination input for all connections. Follows the Relay Connection specification for consistent pagination. ## Forward Pagination Use first and after to paginate forward: graphql streamsConnection(page: { first: 10, after: "cursor..." }) ## Backward Pagination Use last and before to paginate backward: graphql streamsConnection(page: { last: 10, before: "cursor..." })

• first: Int — Number of items to fetch (forward pagination). Default: 50, Max: 500.
• after: String — Cursor to start fetching after (forward pagination).
• last: Int — Number of items to fetch (backward pagination).
• before: String — Cursor to start fetching before (backward pagination).

Conversation

object

A support conversation between tenant and support team. Conversations can contain multiple messages and have a status.

Implements Node.

• id: ID! — The globally unique identifier for this conversation.
• subject: String — Optional subject line for the conversation.
• status: ConversationStatus! (ConversationStatus) — Current status of the conversation.
• lastMessage: Message (Message) — The last message in this conversation.
• unreadCount: Int! — Number of unread messages.
• createdAt: Time! (Time) — When the conversation was created.
• updatedAt: Time! (Time) — When the conversation was last updated.

ConversationStatus

enum

Status of a support conversation.

• OPEN — Conversation is open and awaiting response.
• RESOLVED — Conversation has been resolved.
• PENDING — Conversation is pending action.

DVRChapterMode

enum

How a recording is saved as chapters. Determines how chapter (startMs, endMs) ranges are produced for replay after the broadcast. Configured at the Stream level via updateStream and snapshotted onto the recording when it starts. New streams default to WINDOW_SIZED. UTC-only — civil-time chapters resolve at the edge.

• WINDOW_SIZED — Default. Sequential parts as long as the recording’s own live rewind window, from the recording’s start.
• FIXED_INTERVAL — UTC-only intervalSeconds buckets, anchored at unix epoch 0.
• NONE — Live rewind only: viewers can rewind while live, but nothing is kept after the broadcast and no recording.ready fires.

DeleteSuccess

object

• success: Boolean!
• deletedId: ID!
• pending: Boolean — True when the delete was accepted but is NOT yet finalized (e.g. a stream deletion awaiting the serving cell’s cleanup-tombstone acknowledgement). The operation converges asynchronously; false means fully deleted.

EffectiveRetention

object

Resolved retention horizon for a single asset (DVR, clip, or VOD). Embedded on Clip, DVRRequest, and VodAsset.

• retentionDays: Int! — Days from now until the artifact is scheduled for deletion. 0 = no auto-expire (retentionUntil is null).
• retentionUntil: Time (Time) — Scheduled deletion timestamp. Null when the artifact has no horizon (kept forever).
• source: RetentionSource! (RetentionSource)

Error

interface

Implemented by AuthError, NotFoundError, RateLimitError, ValidationError.

• message: String!
• code: String

GeoBucket

object

• h3Index: String!
• resolution: Int!

Incident

object

• id: ID!
• scope: IncidentScope! (IncidentScope)
• tenantId: ID — Null for platform-scope incidents.
• clusterId: String
• region: String
• alertname: String!
• severity: String!
• status: IncidentStatus! (IncidentStatus)
• resolution: IncidentResolution (IncidentResolution) — Null until the incident is resolved.
• title: String!
• summary: String
• firingAlertCount: Int! — Alerts of this incident that are still firing.
• startedAt: Time! (Time)
• lastAlertAt: Time! (Time)
• acknowledgedAt: Time (Time)
• acknowledgedBy: ID
• assignedTo: ID
• resolvedAt: Time (Time)
• resolvedBy: ID
• createdAt: Time! (Time)
• updatedAt: Time! (Time)

IncidentMutationResult

union

• Member: Incident
• Member: ValidationError
• Member: NotFoundError
• Member: AuthError

IncidentResolution

enum

• AUTO — Every alert of the incident resolved.
• MANUAL — A user resolved the incident.

IncidentScope

enum

• PLATFORM — Platform infrastructure; visible to platform operators only.
• TENANT — A cluster owned by one tenant; visible to that tenant and platform operators.

IncidentStatus

enum

• FIRING
• ACKNOWLEDGED
• RESOLVED

IngestMode

enum

How source media enters a stream.

• PUSH — An encoder pushes RTMP/E-RTMP, SRT, or WHIP into FrameWorks.
• PULL — FrameWorks pulls from a configured upstream URI.
• MANAGED — An operator-managed file, playlist, or process supplies the stream source.

InstanceStatus

enum

Service instance lifecycle status.

• RUNNING — Service is running and healthy.
• STARTING — Service is starting up.
• STOPPING — Service is shutting down.
• STOPPED — Service is stopped.
• ERROR — Service encountered an error.
• UNKNOWN — Service status unknown.

JSON

scalar

ManagedSourceView

object

Safe summary of an operator-managed source. Literal paths, commands, and credentials are intentionally not exposed through the tenant API.

• sourceKind: String! — Managed source form: file, playlist, or exec.
• alwaysOn: Boolean! — Whether the source is kept active without waiting for a viewer.
• placementCount: Int! — Number of source placements requested by the operator configuration.

Message

object

A message within a support conversation.

Implements Node.

• id: ID! — The globally unique identifier for this message.
• conversationId: ID! — The conversation this message belongs to.
• content: String! — The message content.
• sender: MessageSender! (MessageSender) — Who sent this message.
• createdAt: Time! (Time) — When the message was sent.

MessageSender

enum

Who sent a message.

• USER — Message from the user (customer).
• AGENT — Message from a support agent.
• SYSTEM — System activity message (assigned, resolved, etc.).

MonitoringToggle

enum

Per-stream Skipper AI monitoring override.

• INHERIT — Follow the tenant’s billing-tier entitlement (default).
• ON — Monitor this stream regardless of billing tier.
• OFF — Never monitor this stream, even if the tenant is tier-entitled.

Node

interface

Relay-style global node interface. All fetchable objects implement this interface and can be retrieved by their global ID.

Implemented by APIUsageRecord, ArtifactEvent, BufferEvent, ClientMetrics5m, Clip, Cluster, ConnectionEvent, Conversation, InfrastructureNode, Message, NodeMetric, NodeMetricHourly, NodePerformance5m, ProcessingUsageRecord, QualityTierDaily, SigningKey, StorageEvent, StorageUsageRecord, Stream, StreamAnalyticsDaily, StreamConnectionHourly, StreamEvent, StreamHealth5m, StreamHealthMetric, TenantDailyStat, TrackListEvent, ViewerGeoHourly, ViewerHoursHourly, ViewerSession, VodAsset.

• id: ID! — The globally unique identifier for this object.

NodeMetric

object

Implements Node.

• id: ID!
• timestamp: Time! (Time)
• nodeId: String!
• clusterId: String
• cpuUsage: Float!
• memoryTotal: Float — Total memory in MiB.
• memoryUsed: Float — Used memory in MiB.
• diskTotal: Float — Total disk capacity in bytes.
• diskUsed: Float — Used disk capacity in bytes.
• shmTotal: Float — Total shared memory in bytes.
• shmUsed: Float — Used shared memory in bytes.
• networkRx: Float! — Cumulative bytes received (resets on node restart).
• networkTx: Float! — Cumulative bytes sent (resets on node restart).
• upSpeed: Float — Upload throughput in bytes/sec.
• downSpeed: Float — Download throughput in bytes/sec.
• connectionsCurrent: Int
• streamCount: Int
• status: String!
• isHealthy: Boolean
• latitude: Float
• longitude: Float
• metadata: JSON (JSON)

NodeMetricEdge

object

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

NodeMetricHourly

object

Implements Node.

• id: ID!
• timestamp: Time! (Time)
• nodeId: String!
• clusterId: String
• avgCpu: Float!
• peakCpu: Float!
• avgMemory: Float!
• peakMemory: Float!
• avgDisk: Float!
• peakDisk: Float!
• avgShm: Float!
• peakShm: Float!
• totalBandwidthIn: Float!
• totalBandwidthOut: Float!
• wasHealthy: Boolean!

NodeMetricHourlyEdge

object

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

NodeMetrics1hConnection

object

• edges: [NodeMetricHourlyEdge!]! (NodeMetricHourlyEdge)
• nodes: [NodeMetricHourly!]! (NodeMetricHourly)
• pageInfo: PageInfo! (PageInfo)
• totalCount: Int!

NodeMetricsConnection

object

• edges: [NodeMetricEdge!]! (NodeMetricEdge)
• nodes: [NodeMetric!]! (NodeMetric)
• pageInfo: PageInfo! (PageInfo)
• totalCount: Int!

NodeStatus

enum

• HEALTHY
• DEGRADED
• UNHEALTHY

NotFoundError

object

Implements Error.

• message: String!
• code: String
• resourceType: String!
• resourceId: ID!

PageInfo

object

• startCursor: String
• endCursor: String
• hasNextPage: Boolean!
• hasPreviousPage: Boolean!

PlaybackJwtClaimRequirement

object

One required-claim constraint, JSON-encoded for type-flexible matching.

• name: String!
• jsonValue: String! — JSON-encoded expected value (e.g. "pro", true, 42, ["a","b"]).

PlaybackJwtPolicy

object

JWT-gated playback policy. The viewer attaches a JWT minted with one of the allowed signing keys; FrameWorks verifies signature, alg=ES256, exp/iat/nbf, and any required audience / claim constraints.

• allowedKids: [String!]! — Allowed signing key IDs. Empty = any active tenant key.
• requiredAudience: [String!]! — If set, the viewer JWT’s aud claim must contain at least one of these.
• requiredClaimsJson: [PlaybackJwtClaimRequirement!]! (PlaybackJwtClaimRequirement) — Required claim constraints. Each value is the JSON-encoded representation of the expected claim value (so callers can require strings, numbers, booleans, or arrays consistently). Empty = no claim check.

PlaybackPolicy

object

Per-playback-object access policy. Foghorn reads this in the USER_NEW trigger handler; the requiresAuth marker (on the playback object itself) gates whether the full policy is fetched at all.

• type: PlaybackPolicyType! (PlaybackPolicyType)
• jwt: PlaybackJwtPolicy (PlaybackJwtPolicy) — JWT-policy details, populated when type == JWT.
• webhook: PlaybackWebhookPolicy (PlaybackWebhookPolicy) — Webhook-policy details, populated when type == WEBHOOK. Secret is masked.
• allowedOrigins: [String!]! — Sites allowed to embed the content, as normalized scheme://host[:port] origins; * allows any. Empty = no restriction. A browser viewer whose Origin (or Referer) is not listed is denied.

PlaybackPolicyType

enum

• PUBLIC
• JWT
• WEBHOOK

PlaybackWebhookPolicy

object

Webhook-callback playback policy. On every viewer connect, FrameWorks POSTs to the URL with an HMAC-signed body and reads allow/deny from the response. The secret is write-only on input and is never returned by queries.

• url: String!
• timeoutMs: Int! — Outbound POST timeout in milliseconds. Capped server-side at 10000.
• secretMasked: String! — Always ‘redacted’ on read; the actual secret is fieldcrypt-encrypted at rest.
• context: JSON (JSON) — Your JSON object, sent as context in every access request to the URL. Null when unset.

ProcessingUsageRecord

object

Implements Node.

• id: ID!
• timestamp: Time! (Time)
• nodeId: String!
• streamId: ID!
• stream: Stream (Stream)
• processType: String!
• clusterId: String
• originClusterId: String
• controlCellId: String
• trackType: String
• durationMs: Int!
• inputCodec: String
• outputCodec: String
• segmentNumber: Int
• width: Int
• height: Int
• renditionCount: Int
• broadcasterUrl: String
• uploadTimeUs: Int
• livepeerSessionId: String
• segmentStartMs: Int
• inputBytes: Float
• outputBytesTotal: Float
• attemptCount: Int
• turnaroundMs: Int
• speedFactor: Float
• renditionsJson: String
• inputFrames: Int
• outputFrames: Int
• decodeUsPerFrame: Int
• transformUsPerFrame: Int
• encodeUsPerFrame: Int
• isFinal: Boolean
• inputFramesDelta: Int
• outputFramesDelta: Int
• inputBytesDelta: Float
• outputBytesDelta: Float
• inputWidth: Int
• inputHeight: Int
• outputWidth: Int
• outputHeight: Int
• inputFpks: Int
• outputFpsMeasured: Float
• sampleRate: Int
• channels: Int
• sourceTimestampMs: Int
• sinkTimestampMs: Int
• sourceAdvancedMs: Int
• sinkAdvancedMs: Int
• rtfIn: Float
• rtfOut: Float
• pipelineLagMs: Int
• outputBitrateBps: Int

PullSourceEvent

object

A single pull-source resolution outcome from Foghorn’s STREAM_SOURCE handler. Append-only; written every time a pull+ stream’s source is re-evaluated (typically on each Mist input start).

• id: ID!
• internalName: String!
• eventKind: String! — ‘resolved’ | ‘not_found’ | ‘disabled’ | ‘blocked_uri’ | ‘cluster_not_allowed_delegate’ | ‘commodore_error’ | ‘foghorn_base_unresolved’
• detail: String
• createdAt: Time! (Time)

PullSourceView

object

Redacted pull-input source configuration.

• sourceUriRedacted: String! — Redacted upstream URI with credentials removed.
• enabled: Boolean! — Whether the media plane may pull from the source.
• class: String! — Eligibility class: public or private.

PushTarget

object

• id: ID!
• streamId: ID!
• platform: String — Platform identifier (twitch, youtube, facebook, kick, x, custom).
• name: String! — User-friendly label for this target.
• videoChoice: String! — AUTO, SOURCE_VIDEO, or PROCESSED_VIDEO. Audio is selected independently.
• targetUri: String! — Target URI (masked in responses — stream key portion is redacted).
• isEnabled: Boolean! — Whether this target is enabled for automatic push on stream start.
• status: String! — Current push status: pending, pushing, retrying, stopping, idle, or failed.
• lastError: String — Last error message if push failed.
• reasonCode: String — Stable machine-readable lifecycle reason code.
• lastPushedAt: Time (Time) — When this target last successfully pushed.
• createdAt: Time! (Time)

RateLimitError

object

Implements Error.

• message: String!
• code: String
• retryAfter: Int

RetentionSource

enum

Source of an effective retention horizon. Mirrors the cascade layers used at artifact create / asset reset (per-asset override → per-stream override → tenant per-class default → tier entitlement clamp).

• TENANT_DEFAULT
• PER_STREAM_OVERRIDE
• PER_ASSET_OVERRIDE
• TIER_ENTITLEMENT

RoutingEvent

object

• timestamp: Time! (Time)
• streamId: ID!
• stream: Stream (Stream)
• selectedNode: String!
• nodeId: String
• status: String!
• details: String
• score: Int
• clientCountry: String
• clientLatitude: Float
• clientLongitude: Float
• clientBucket: GeoBucket (GeoBucket)
• nodeLatitude: Float
• nodeLongitude: Float
• nodeName: String
• nodeBucket: GeoBucket (GeoBucket)
• routingDistance: Float
• candidatesCount: Int
• latencyMs: Float
• eventType: String
• source: String
• streamTenantId: ID
• clusterId: String
• remoteClusterId: String
• selectedClusterId: String
• controlCellId: String
• originClusterId: String

ServiceInstance

object

• id: ID!
• instanceId: String!
• clusterId: String!
• nodeId: String
• serviceId: String!
• version: String
• port: Int
• processId: Int
• containerId: String
• status: InstanceStatus! (InstanceStatus)
• healthStatus: NodeStatus! (NodeStatus)
• startedAt: Time (Time)
• stoppedAt: Time (Time)
• lastHealthCheck: Time (Time)

ServiceInstanceEdge

object

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

ServiceInstanceHealth

object

• instanceId: String!
• serviceId: String!
• clusterId: String!
• protocol: String!
• host: String
• port: Int!
• healthEndpoint: String
• status: String!
• lastHealthCheck: Time (Time)

ServiceInstancesConnection

object

• edges: [ServiceInstanceEdge!]! (ServiceInstanceEdge)
• nodes: [ServiceInstance!]! (ServiceInstance)
• pageInfo: PageInfo! (PageInfo)
• totalCount: Int!

SourceLocation

object

• mode: SourceLocationMode! (SourceLocationMode)
• clusters: [SourceLocationCluster!]! (SourceLocationCluster) — Empty unless mode is RESTRICTED.
• avoidNodeIds: [ID!]! — Empty unless mode is RESTRICTED.

SourceLocationCluster

object

• clusterId: ID!
• nodeIds: [ID!]! — Empty means any node of the cluster.

SourceLocationMode

enum

Where a stream’s source may be ingested. It is a summary of the stream’s own ingest placement rules.

• ANY — No stream-level restriction; FrameWorks chooses among the tenant’s entitled clusters.
• RESTRICTED — Only the listed clusters, optionally narrowed to specific nodes and excluding avoided nodes.
• CUSTOM — The stream’s own ingest rules contain constraints this summary cannot express. Read-only here; edit them in the stream’s placement rules.

StorageArtifactKind

enum

• VOD
• DVR
• CHAPTER
• CLIP

StorageCostProjection

object

Marginal per-asset storage cost projection. Used by the customer-facing storage browser to show “this clip costs you ~$0.01/day”. The unit is the tier’s currency (typically EUR). Rating prices storage per GiB-month (a fixed 730-hour month); perMonth = GiB × price, perDay = perMonth × 24 / 730.

• perDay: Float!
• perMonth: Float!
• currency: String!

StorageEvent

object

Implements Node.

• id: ID!
• timestamp: Time! (Time)
• streamId: ID!
• stream: Stream (Stream)
• assetHash: String!
• action: String!
• assetType: String!
• sizeBytes: Float!
• s3Url: String
• localPath: String
• nodeId: String!
• clusterId: String
• originClusterId: String
• controlCellId: String
• durationMs: Int
• warmDurationMs: Int
• error: String

Stream

object

A live stream configuration with real-time operational metrics. Streams are the core entity for broadcasting and viewing live content.

Implements Node.

• id: ID! — Global unique identifier for Relay compatibility.
• streamId: String! — Public stream UUID used for analytics and service APIs (not the Relay ID).
• name: String! — Human-readable display name for the stream.
• description: String — Optional description for the stream.
• streamKey: String — Secret key for publisher-authenticated ingest; null for pull and managed sources. The key lets its holder publish to the stream, so an API token needs the streams:write scope: without it this field is null and the response carries a FORBIDDEN error at its path.
• playbackId: String! — Public identifier for playback URLs.
• record: Boolean! — Whether DVR recording is enabled for this stream.
• liveVideoAbr: String! — INHERIT or OFF for live video renditions.
• ingestMode: IngestMode! (IngestMode) — How source media enters the stream.
• pullSource: PullSourceView (PullSourceView) — Pull-source config for pull streams; null for push streams.
• managedSource: ManagedSourceView (ManagedSourceView) — Safe source summary for managed streams; null for push and pull streams.
• sourceLocation: SourceLocation! (SourceLocation) — Where the stream’s source may be ingested, derived from the stream’s own ingest placement rules.
• createdAt: Time! (Time) — When this stream was created.
• updatedAt: Time! (Time) — When this stream was last modified.
• metrics: StreamMetrics (StreamMetrics) — Real-time operational metrics from the data plane. Includes viewer counts, quality metrics, and throughput data. Lazily loaded from ClickHouse analytics, so an API token needs the analytics:read scope: without it this field is null and the response carries a FORBIDDEN error at its path.
• pushTargets: [PushTarget!]! (PushTarget) — Configured multistream push targets for this stream.
• playbackPolicy: PlaybackPolicy (PlaybackPolicy) — Playback access policy. null/PUBLIC = anyone with the playbackId can watch.
• dvrChapterMode: DVRChapterMode (DVRChapterMode) — How saved recordings are split into chapters. Snapshotted when a recording starts; changes apply from the next broadcast. NONE = live rewind only, nothing kept after the broadcast.
• dvrChapterIntervalSeconds: Int — Chapter interval in seconds. Required when dvrChapterMode = FIXED_INTERVAL, ignored otherwise. Minimum 3600 (1 hour).
• monitoring: MonitoringToggle! (MonitoringToggle) — Per-stream Skipper monitoring override (INHERIT follows tier).
• recentPullSourceEvents: [PullSourceEvent!] (PullSourceEvent) — Recent pull-source resolution events for pull streams. Captures the customer-facing resolution outcome (resolved, not_found, disabled, blocked_uri, cluster_not_allowed_delegate, commodore_error, foghorn_base_unresolved). Null for push streams.
  • limit: Int (default 50)
• thumbnailAssets: ThumbnailAssets (ThumbnailAssets) — Server-resolved Chandler URLs for the stream’s poster and sprite thumbnails. Derived from active_ingest_cluster_id + stream_id at SELECT time. Null when the stream has never been live; the poster.jpg 404s until Helmsman uploads its first frame, which the player’s fallback chain handles.
• retentionOverrides: StreamRetentionOverrides (StreamRetentionOverrides) — Per-stream retention overrides for DVR and clips. Null when the stream has no overrides set (inherits the tenant default). VOD uploads aren’t stream-bound, so they don’t appear here.

StreamEvent

object

Implements Node.

• id: ID!
• eventId: ID!
• streamId: ID
• stream: Stream (Stream)
• nodeId: String
• type: StreamEventType! (StreamEventType)
• status: StreamStatus (StreamStatus)
• timestamp: Time! (Time)
• details: String
• payload: JSON (JSON)
• source: StreamEventSource! (StreamEventSource)
• bufferState: String
• hasIssues: Boolean
• trackCount: Int
• qualityTier: String
• primaryWidth: Int
• primaryHeight: Int
• primaryFps: Float
• primaryCodec: String
• primaryBitrate: Int
• downloadedBytes: Float
• uploadedBytes: Float
• totalViewers: Int
• totalInputs: Int
• totalOutputs: Int
• viewerSeconds: Float
• requestUrl: String
• protocol: String
• latitude: Float
• longitude: Float
• location: String
• countryCode: String
• city: String
• sourceRegion: String!
• sourceClusterId: String!
• streamOriginRegion: String!
• streamOriginClusterId: String!
• schemaVersion: Int!

StreamEventSource

enum

• HISTORICAL
• LIVE

StreamEventType

enum

• STREAM_LIFECYCLE_UPDATE
• STREAM_START
• STREAM_END
• BUFFER_UPDATE
• TRACK_LIST_UPDATE
• PLAY_REWRITE
• STREAM_SOURCE

StreamMetrics

object

Real-time operational metrics for a stream from the analytics data plane. Updated frequently while stream is live, represents latest known state.

• status: StreamStatus! (StreamStatus) — Current lifecycle status of the stream (OFFLINE, CONNECTING, LIVE, etc.).
• isLive: Boolean! — Whether the stream is currently broadcasting.
• currentViewers: Int! — Number of viewers currently watching.
• startedAt: Time (Time) — When the current live session started (null if offline).
• updatedAt: Time! (Time) — When these metrics were last updated.
• nodeId: String — ID of the edge node handling this stream.
• trackCount: Int — Number of quality tracks available.
• totalInputs: Int — Total ingest connections to this stream.
• uploadedBytes: Float! — Total bytes uploaded (ingested) for current session.
• downloadedBytes: Float! — Total bytes downloaded (egress) for current session.
• viewerSeconds: Float! — Total viewer-seconds accumulated.
• packetsSent: Float — Total packets sent to viewers.
• packetsLost: Float — Total packets lost in transit.
• packetsRetransmitted: Float — Total packets retransmitted.
• bufferState: String — Buffer health state (HEALTHY, WARNING, CRITICAL).
• qualityTier: String — Highest quality tier available (4K, 1080p, 720p, etc.).
• primaryWidth: Int — Primary video track width in pixels.
• primaryHeight: Int — Primary video track height in pixels.
• primaryFps: Float — Primary video track framerate.
• primaryCodec: String — Primary video codec (H.264, H.265, VP9, AV1).
• primaryBitrate: Int — Primary video bitrate in kbps.
• hasIssues: Boolean — Whether the stream has active quality issues.
• issuesDescription: String — Human-readable description of current issues.

StreamRetentionOverrides

object

Per-stream retention overrides for DVR and clips. VOD uploads aren’t stream-bound, so they have no stream-level knob here.

• streamId: ID!
• dvrRetentionDaysOverride: Int — Null = no override (inherit tenant default). 0 = no auto-expire.
• clipRetentionDaysOverride: Int

StreamStatus

enum

Live stream status.

• OFFLINE — Stream is not broadcasting.
• LIVE — Stream is currently live.
• RECORDING — Stream is live and recording.
• ENDED — Stream has ended (no longer live).

StreamTrack

object

• trackName: String!
• trackType: String!
• codec: String
• bitrateKbps: Int
• bitrateBps: Int
• buffer: Int
• jitter: Int
• width: Int
• height: Int
• fps: Float
• resolution: String
• hasBFrames: Boolean
• channels: Int
• sampleRate: Int

ThumbnailAssets

object

Chandler-served thumbnail asset URLs (poster, sprite, VTT cues). URL shape is {chandlerBase}/assets/{assetKey}/poster.jpg, /assets/{assetKey}/sprite.jpg, /assets/{assetKey}/sprite.vtt — Chandler serves the object key directly, no version resolution. assetKey is stream_id for live streams; clip_hash / dvr_hash / vod_hash (= artifact_hash) for artifacts.

• posterUrl: String!
• spriteVttUrl: String!
• spriteJpgUrl: String!
• assetKey: String!

Time

scalar

TimeRangeInput

input_object

Time range for filtering time-series data.

• start: Time! (Time) — Start of the time range.
• end: Time! (Time) — End of the time range.

ValidationError

object

Implements Error.

• message: String!
• code: String
• field: String
• constraint: String

VodAsset

object

A Video-on-Demand asset uploaded by the tenant. VOD assets can be played back using the playbackId in playback URLs.

Implements Node.

• id: ID! — Global unique identifier for Relay compatibility.
• artifactHash: String! — Internal hash used for playback URL resolution.
• playbackId: String! — Public playback identifier for generating playback URLs.
• streamId: String — Source stream UUID for stream-derived VOD artifacts such as DVR chapters.
• originType: String — Registry origin kind. Null/user_upload for ordinary uploads; dvr_chapter for finalized DVR chapters.
• originId: String — Origin entity id, such as DVR chapter_id when originType=dvr_chapter.
• title: String — Optional display title for the asset.
• description: String — Optional description of the asset content.
• filename: String — Original filename when uploaded.
• status: VodAssetStatus! (VodAssetStatus) — Current processing/storage status of the asset.
• storageLocation: String! — Where the asset is stored (s3, local, freezing).
• syncStatus: String — Current S3 sync state (pending, in_progress, synced, failed, lost_local).
• hasLocalCopy: Boolean — Present full local node copy (origin or cache): true when at least one node holds a complete local copy, false when none remain (playback via Helmsman’s read-through relay from S3). Null when the placement overlay (Periscope) is unavailable — unknown, not ‘no local copy’. Durable S3-only state is derived by consumers as isSynced && hasLocalCopy == false.
• isSynced: Boolean! — True when S3 has an authoritative copy.
• isFinalized: Boolean! — True when the S3 copy includes the Mist .dtsh index.
• sizeBytes: Float — File size in bytes (available after validation).
• durationMs: Int — Video duration in milliseconds.
• resolution: String — Video resolution (e.g., ‘1920x1080’).
• videoCodec: String — Video codec (h264, h265, vp9, av1).
• audioCodec: String — Audio codec (aac, opus).
• bitrateKbps: Int — Average bitrate in kbps.
• createdAt: Time! (Time) — When the asset was created/uploaded.
• updatedAt: Time! (Time) — When the asset was last modified.
• expiresAt: Time (Time) — Optional expiration time for auto-deletion.
• errorMessage: String — Error message if processing failed.
• playbackPolicy: PlaybackPolicy (PlaybackPolicy) — Playback access policy. null/PUBLIC = anyone with the playbackId can watch.
• thumbnailAssets: ThumbnailAssets (ThumbnailAssets) — Server-resolved Chandler URLs for the VOD’s poster and sprite thumbnails. Null until Foghorn confirms the thumbnail upload.
• effectiveRetention: EffectiveRetention (EffectiveRetention) — Resolved retention horizon with the source of the decision (per-asset override → per-stream override → tenant default → tier entitlement). Null while the asset’s retention_until column is unset (infinite).
• storageCost: StorageCostProjection (StorageCostProjection) — Marginal storage cost for this asset on the tenant’s tier. Null when the tenant has no storage meter (self-hosted, fully tenant-private cluster). Computed from sizeBytes in GiB × the tier’s price per GiB-month.

VodAssetStatus

enum

VOD asset processing status.

• UPLOADING — S3 multipart upload in progress.
• PROCESSING — Upload complete, validating and extracting metadata.
• READY — Validated and ready for playback.
• FAILED — Validation failed or upload error.
• DELETED — Marked for deletion.
• EXPIRED — Multipart upload session deadline elapsed without completion; client must restart.