Skip to main content

Force an Output onto a Failover Hop

POST 
/qlibs/:qlibid/q/:qhit/call/live/outputs/:outid/ctrl/hop

Switch a running output onto a specific hop of its input failover chain (hop=0 is the primary), bypassing the anti-flap protection that gates automatic failover (failover_policy).

Unlike the other ctrl/ operations this changes no configuration: nothing is written to the outputs object and no new content version is created. It is purely ephemeral runtime state, with three consequences:

  • Transient, not a pin. Automatic failover keeps full authority - if the forced hop later goes unhealthy, the output fails over off it as usual. The choice is not re-applied after an output restart, and is lost when the output goes idle.
  • Per node. It affects only the node that receives the call, and returns 404 on a node that is not currently running the output. An srt_pull output served from several nodes must be forced on each of them.
  • Applied asynchronously. The switch is performed by the failover monitor within about a second, which is why this returns 202 and why the failover.active_hop in the response body still shows the previous hop. Poll GET .../state to confirm the switch.

Only the requested hop is attempted - the call never silently lands on a different one. If that hop cannot be activated (its stream is unresolvable, or it is packaged incompatibly with the stream currently being served) the output simply stays where it is, and the reason appears as error on that hop in HopState. On success, failover.last_failover_reason in FailoverState records that the switch was forced.

Request​

Responses​

The switch was accepted and will be applied within about a second. The body is the output's state as of acceptance, so failover.active_hop still shows the hop that was active when the call was made.