Streams

GraphQL schema reference · API guide · SDKs

Live streams, stream keys, push targets, and ingest endpoint resolution.

Types used by more than one domain are on Shared types.

Queries

Query.resolveIngestEndpoint

Resolve a stream key to ingest endpoints for StreamCrafter. Returns node-specific advertised protocols. A requested protocol filters candidates before ranking; it is not permission to substitute a different protocol.

resolveIngestEndpoint(
  streamKey: String!
  protocol: MediaIngestProtocol
): IngestEndpointResponse

Returns: IngestEndpointResponse (IngestEndpointResponse)

Arguments

streamKey: String! — The stream key.
protocol: MediaIngestProtocol (MediaIngestProtocol)

SDK

Operation	TypeScript	Go	Python
ResolveIngestEndpoint	`ResolveIngestEndpointDocument`	`ResolveIngestEndpoint`	`resolve_ingest_endpoint`

Query.stream

Fetch a single stream by its global ID. An API token needs the streams:read or streams:write scope. Stream.streamKey needs streams:write.

stream(
  id: ID!
): Stream

Returns: Stream (Stream)

Arguments

id: ID! — The global ID of the stream.

SDK

Operation	Selects	TypeScript	Go	Python
GetRecentPullSourceEvents	`stream.recentPullSourceEvents`	`GetRecentPullSourceEventsDocument`	`GetRecentPullSourceEvents`	`get_recent_pull_source_events`
GetStream	`stream`	`GetStreamDocument`	`GetStream`	`get_stream`
GetStreamKey	`stream.streamKey`	`GetStreamKeyDocument`	`GetStreamKey`	`get_stream_key`
GetStreamMetrics	`stream.metrics`	`GetStreamMetricsDocument`	`GetStreamMetrics`	`get_stream_metrics`
ListPushTargets	`stream.pushTargets`	`ListPushTargetsDocument`	`ListPushTargets`	`list_push_targets`

Query.streamKeysConnection

List all stream keys for a specific stream. Stream keys are publishing credentials, so an API token needs the streams:write scope.

streamKeysConnection(
  page: ConnectionInput
  streamId: ID!
): StreamKeysConnection!

Returns: StreamKeysConnection! (StreamKeysConnection)

Arguments

page: ConnectionInput (ConnectionInput) — Pagination options.
streamId: ID! — The stream ID to list keys for (Stream.id, Relay global ID).

SDK

Operation	TypeScript	Go	Python
ListStreamKeys	`ListStreamKeysDocument`	`ListStreamKeys`	`list_stream_keys`

Query.streamingConfig

Cluster-aware streaming configuration for the authenticated tenant. Returns preferred and official cluster domains for building protocol-specific URLs. Null when not authenticated or cluster routing unavailable — frontend falls back to env vars.

streamingConfig: StreamingConfig

Returns: StreamingConfig (StreamingConfig)

SDK

Operation	TypeScript	Go	Python
GetStreamingConfig	`GetStreamingConfigDocument`	`GetStreamingConfig`	`get_streaming_config`

Query.streamsConnection

List all streams for the current tenant with pagination. An API token needs the streams:read or streams:write scope. Stream.streamKey needs streams:write.

streamsConnection(
  page: ConnectionInput
  search: String
): StreamsConnection!

Returns: StreamsConnection! (StreamsConnection)

Arguments

page: ConnectionInput (ConnectionInput) — Pagination options.
search: String — Optional server-side name search (title / internal name). Enables an account-wide picker instead of only the first page.

SDK

Operation	Selects	TypeScript	Go	Python
ListStreamMetrics	`streamsConnection.nodes.metrics`	`ListStreamMetricsDocument`	`ListStreamMetrics`	`list_stream_metrics`
ListStreams	`streamsConnection`	`ListStreamsDocument`	`ListStreams`	`list_streams`

Query.validateStreamKey

Validate a stream key and return the associated stream info.

validateStreamKey(
  streamKey: String!
): StreamValidation

Returns: StreamValidation (StreamValidation)

Arguments

streamKey: String! — The stream key to validate.

SDK

Operation	TypeScript	Go	Python
GetValidateStreamKey	`GetValidateStreamKeyDocument`	`GetValidateStreamKey`	`get_validate_stream_key`

Mutations

Mutation.createPushTarget

Add a multistream push target to a stream. When the stream goes live, it will automatically push to all enabled targets.

createPushTarget(
  streamId: ID!
  input: CreatePushTargetInput!
): PushTarget!

Returns: PushTarget! (PushTarget)

Arguments

streamId: ID! — The stream ID (Stream.id, Relay global ID).
input: CreatePushTargetInput! (CreatePushTargetInput) — Push target configuration.

SDK

Operation	TypeScript	Go	Python
CreatePushTarget	`CreatePushTargetDocument`	`CreatePushTarget`	`create_push_target`

Mutation.createStream

Create a new stream for live broadcasting.

createStream(
  input: CreateStreamInput!
): CreateStreamResult!

Returns: CreateStreamResult! (CreateStreamResult)

Arguments

input: CreateStreamInput! (CreateStreamInput) — Stream configuration.

SDK

Operation	TypeScript	Go	Python
CreateStream	`CreateStreamDocument`	`CreateStream`	`create_stream`

Mutation.createStreamKey

Create an additional stream key for a stream.

createStreamKey(
  streamId: ID!
  input: CreateStreamKeyInput!
): CreateStreamKeyResult!

Returns: CreateStreamKeyResult! (CreateStreamKeyResult)

Arguments

streamId: ID! — The stream ID (Stream.id, Relay global ID).
input: CreateStreamKeyInput! (CreateStreamKeyInput) — Stream key configuration.

SDK

Operation	TypeScript	Go	Python
CreateStreamKey	`CreateStreamKeyDocument`	`CreateStreamKey`	`create_stream_key`

Mutation.deletePushTarget

Delete a multistream push target.

deletePushTarget(
  id: ID!
): DeleteSuccess!

Returns: DeleteSuccess! (DeleteSuccess)

Arguments

id: ID! — The push target ID.

SDK

Operation	TypeScript	Go	Python
DeletePushTarget	`DeletePushTargetDocument`	`DeletePushTarget`	`delete_push_target`

Mutation.deleteStream

Delete a stream and all associated data.

deleteStream(
  id: ID!
): DeleteStreamResult!

Returns: DeleteStreamResult! (DeleteStreamResult)

Arguments

id: ID! — The stream ID to delete.

SDK

Operation	TypeScript	Go	Python
DeleteStream	`DeleteStreamDocument`	`DeleteStream`	`delete_stream`

Mutation.deleteStreamKey

Delete a stream key.

deleteStreamKey(
  streamId: ID!
  keyId: ID!
): DeleteStreamKeyResult!

Returns: DeleteStreamKeyResult! (DeleteStreamKeyResult)

Arguments

streamId: ID! — The stream ID (Stream.id, Relay global ID).
keyId: ID! — The key ID to delete.

SDK

Operation	TypeScript	Go	Python
DeleteStreamKey	`DeleteStreamKeyDocument`	`DeleteStreamKey`	`delete_stream_key`

Mutation.refreshStreamKey

Generate a new stream key, invalidating the old one.

refreshStreamKey(
  id: ID!
): UpdateStreamResult!

Returns: UpdateStreamResult! (UpdateStreamResult)

Arguments

id: ID! — The stream ID.

SDK

Operation	TypeScript	Go	Python
RefreshStreamKey	`RefreshStreamKeyDocument`	`RefreshStreamKey`	`refresh_stream_key`

Mutation.updatePushTarget

Update a multistream push target.

updatePushTarget(
  id: ID!
  input: UpdatePushTargetInput!
): PushTarget!

Returns: PushTarget! (PushTarget)

Arguments

id: ID! — The push target ID.
input: UpdatePushTargetInput! (UpdatePushTargetInput) — Fields to update.

SDK

Operation	TypeScript	Go	Python
UpdatePushTarget	`UpdatePushTargetDocument`	`UpdatePushTarget`	`update_push_target`

Mutation.updateStream

Update an existing stream’s configuration.

updateStream(
  id: ID!
  input: UpdateStreamInput!
): UpdateStreamResult!

Returns: UpdateStreamResult! (UpdateStreamResult)

Arguments

id: ID! — The stream ID.
input: UpdateStreamInput! (UpdateStreamInput) — Updated stream configuration.

SDK

Operation	TypeScript	Go	Python
UpdateStream	`UpdateStreamDocument`	`UpdateStream`	`update_stream`

Types

CreatePushTargetInput

input_object

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 for RTMP targets.
targetUri: String! — Full target URI including stream key (e.g., rtmp://live.twitch.tv/app/live_xxxx).

CreateStreamInput

input_object

Input for creating a new live stream.

name: String! — Human-readable name for the stream.
description: String — Optional description for the stream.
record: Boolean — Enable DVR recording (default: false).
liveVideoAbr: String — Live video renditions: INHERIT uses the tier policy; OFF keeps source video and audio conversion.
ingestMode: IngestMode (IngestMode) — Source ingest model. Defaults to PUSH.
pullSource: PullSourceInput (PullSourceInput) — Pull-source configuration. Required when ingestMode is PULL.
sourceLocation: SourceLocationInput (SourceLocationInput) — Where the source may be ingested. Omitted means ANY. Required for private and multicast pull sources.

CreateStreamKeyInput

input_object

Input for creating an additional stream key.

name: String! — Human-readable name for the key.

CreateStreamKeyResult

union

Member: StreamKey
Member: ValidationError
Member: NotFoundError
Member: AuthError

CreateStreamResult

union

Member: Stream
Member: ValidationError
Member: AuthError

DeleteStreamKeyResult

union

Member: DeleteSuccess
Member: NotFoundError
Member: AuthError

DeleteStreamResult

union

Member: DeleteSuccess
Member: NotFoundError
Member: AuthError

IngestEndpoint

object

nodeId: String!
baseUrl: String!
whipUrl: String
rtmpUrl: String
srtUrl: String
region: String
loadScore: Float
kind: IngestEndpointKind! (IngestEndpointKind)
clusterId: String!

IngestEndpointKind

enum

INGEST_ENDPOINT_KIND_UNSPECIFIED
INGEST_ENDPOINT_KIND_TENANT_ALIAS
INGEST_ENDPOINT_KIND_ROOT_POOL
INGEST_ENDPOINT_KIND_CLUSTER_POOL
INGEST_ENDPOINT_KIND_NODE_SPECIFIC

IngestEndpointResponse

object

primary: IngestEndpoint! (IngestEndpoint)
fallbacks: [IngestEndpoint!]! (IngestEndpoint)
metadata: IngestMetadata (IngestMetadata)

IngestMetadata

object

streamId: ID!
stream: Stream (Stream)
streamKey: String!
tenantId: String!
recordingEnabled: Boolean!
title: String
description: String

MediaIngestProtocol

enum

WHIP
RTMP
SRT

PullSourceInput

input_object

sourceUri: String — Upstream RTSP, SRT, RIST, HLS, DTSC, or TS source URI. Required when creating or replacing a pull source.
enabled: Boolean — Whether the media plane may pull from the source.

SourceLocationClusterInput

input_object

clusterId: ID!
nodeIds: [ID!]! — Nodes of this cluster the source may run on. Empty means any node of the cluster. Only nodes of clusters the tenant owns are accepted.

SourceLocationInput

input_object

Replaces the stream’s own ingest restriction. Private and multicast pull sources require RESTRICTED with clusters that allow private pull sources.

mode: SourceLocationMode! (SourceLocationMode) — ANY or RESTRICTED. CUSTOM is rejected.
clusters: [SourceLocationClusterInput!]! (SourceLocationClusterInput) — Required and non-empty for RESTRICTED; must be empty for ANY.
avoidNodeIds: [ID!]! — Nodes the source must never run on. Only nodes of clusters the tenant owns are accepted.

StreamEdge

object

cursor: String!
node: Stream! (Stream)

StreamKey

object

id: ID!
streamId: ID!
stream: Stream (Stream)
keyValue: String! — The publishing secret. Stream keys are read only through operations that need the streams:write scope.
keyName: String
isActive: Boolean!
lastUsedAt: Time (Time)
createdAt: Time! (Time)

StreamKeyEdge

object

cursor: String!
node: StreamKey! (StreamKey)

StreamKeysConnection

object

edges: [StreamKeyEdge!]! (StreamKeyEdge)
nodes: [StreamKey!]! (StreamKey)
pageInfo: PageInfo! (PageInfo)
totalCount: Int!

StreamValidation

object

status: ValidationStatus! (ValidationStatus)
streamKey: String!
error: String

StreamingConfig

object

preferredClusterLabel: String
ingestDomain: String
edgeDomain: String
playDomain: String
officialClusterLabel: String
officialIngestDomain: String
officialEdgeDomain: String
officialPlayDomain: String
globalIngestDomain: String
globalEdgeDomain: String
globalPlayDomain: String
globalLivepeerDomain: String
tenantIngestDomain: String
tenantEdgeDomain: String
tenantPlayDomain: String
tenantLivepeerDomain: String
srtPort: Int
rtmpPort: Int

StreamsConnection

object

edges: [StreamEdge!]! (StreamEdge)
nodes: [Stream!]! (Stream)
pageInfo: PageInfo! (PageInfo)
totalCount: Int!

UpdatePushTargetInput

input_object

name: String — Updated label.
videoChoice: String — AUTO, SOURCE_VIDEO, or PROCESSED_VIDEO for RTMP targets.
targetUri: String — Updated target URI.
isEnabled: Boolean — Enable or disable this target.

UpdateStreamInput

input_object

Input for updating an existing stream. All fields are optional - only provided fields are updated.

name: String — New name for the stream.
description: String — New description for the stream.
record: Boolean — Enable or disable DVR recording.
liveVideoAbr: String — INHERIT uses the tier policy; OFF disables live video renditions from the next ingest.
ingestMode: IngestMode (IngestMode) — Ingest model cannot be changed after create; sending a different value returns a validation error.
pullSource: PullSourceInput (PullSourceInput) — Update the pull-source configuration for an existing pull stream.
sourceLocation: SourceLocationInput (SourceLocationInput) — Replace where the source may be ingested. Omitted keeps the current location. Rejected for managed streams.
dvrChapterMode: DVRChapterMode (DVRChapterMode) — How saved recordings are split into chapters. Snapshotted when a recording starts; changes apply from the next broadcast, not to a recording in progress. NONE keeps live rewind only: viewers can rewind while live, but nothing is kept after the broadcast.
dvrChapterIntervalSeconds: Int — Chapter interval in seconds. Required when dvrChapterMode = FIXED_INTERVAL. Minimum 3600 (1 hour). Send 0 with any other mode to clear a stored interval.
monitoring: MonitoringToggle (MonitoringToggle) — Per-stream Skipper monitoring override. INHERIT follows the tenant tier.

UpdateStreamResult

union

Member: Stream
Member: ValidationError
Member: NotFoundError
Member: AuthError

ValidationStatus

enum

VALID
INVALID
ERROR