Monitor live resources

The Live API provides three ways to observe a running resource: a lightweight state endpoint for polling, a full status object on the resource GET response, and a monitoring object that carries thumbnail and metadata URLs for visual inspection.

Check the current state

The state endpoint returns only the current state of the resource. Use it in polling loops rather than reading the full resource each time.

• Terminal window

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/live/liveChannels/my-channel/state" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

The response contains status.state. This is a separate concept from the spec.state you set (which only has two values, Stopped and Running). status.state reflects everything the platform reports while getting there, and has 13 possible values:

"", Pending, Allocating, Allocated, Starting, Started, Running,
Updating, Stopping, Stopped, Deleting, Deleted, UnableToStart

Compare the reported state with the desired state and check status.info on the full resource for any informational message. Do not assume every resource visits every intermediate value. Use the same pattern for liveEvents, staticMultiviewChannels, and staticMultiviewEvents by substituting the resource type in the path.

Handle a resource that does not start

Starting means the resource is still transitioning. The API does not guarantee that a resource leaves Starting within a fixed time, so set your own timeout in any polling loop rather than waiting indefinitely. If a resource stays in Starting for longer than you expect, check that the contribution encoder is sending media. Check the source URL, listener allow list, encryption settings, and encoder connection status alongside status.state and status.info. Confirm that every referenced resource still exists. Check the asset named in spec.transform.assetName, the sources or content named in spec.inputs, and the config named in spec.transform.encodingLive.configRef.

Read full status

The full GET response includes status.state, input status, output status, and the assigned device and site:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/live/liveChannels/my-channel?\$detailedStatus=true" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

The status object includes:

Inspect input and output status

Input status

Each entry in status.inputs reflects the resolved assignment for that input. See Resolving content for how the platform gets from contentName to one of these:

When an input is resolved, sourceName identifies the assigned source or upstreamFlowName identifies the upstream flow. Both can be empty when no assignment has been resolved. None of these fields report whether media is arriving. They describe assignment and resolution, not what is flowing through the input. A source Active state, successful Domain Name System (DNS) resolution, or an established listener connection has the same boundary: each confirms assignment or use, not live media flow. Read the current input assignments from each response; do not substitute the desired spec.inputs values when a status field is empty.

Output status

Each entry in status.outputs shows where output is being sent:

Read metrics

The full resource response includes status.metrics, a dictionary keyed by metric name. Inspect the returned metrics alongside resource state, input assignments, and playback. A resource state or a single metric is not a substitute for checking that the expected sources reach the output. For project-level metrics export and monitoring storage, see Monitor MK.IO services. Use the export URL returned for your project and retain samples in your monitoring system when you need history.

Verify media delivery

Check status.inputs against the source or content references in spec.inputs.

• Confirm that each contribution encoder is sending to its source’s returned URL.

• Use the monitoring URLs below for a preview when they are returned.

• Publish the output asset and verify the expected video and audio in a compatible player. For multiview, check every tile.

An Active source means it is in use. Input assignment, resource state, and a reachable manifest each verify a different part of the workflow; none alone proves that the current media reaches viewers.

Access monitoring URLs

The status.monitoring object provides URLs for visual monitoring. Each key is a monitoring context name. Each value contains:

The contexts available depend on the transform type and configuration. Fetch the thumbnail URL to display a visual preview of the stream. Fetch the metadata URL for structured data about the current stream state.

"monitoring": {
  "encode": {
    "thumbnailUrl": "https://...",
    "metadataUrl": "https://..."
  }
}