Live

Get a live stream

Fetch one live stream with its status, encoding stats and the status and watch URL of each destination.

GET https://social-publish-api.onrender.com/v1/live/{id}

Poll this endpoint (every 5–10 s is plenty) to follow a stream from scheduled to live to ended.

Request

cURLNode.js

curl https://social-publish-api.onrender.com/v1/live/c0ffee00-1234-4abc-9def-0123456789ab \
  -H "x-access-key: $RELAYCAST_API_KEY"

const res = await fetch(`https://social-publish-api.onrender.com/v1/live/${id}`, { headers: { "x-access-key": process.env.RELAYCAST_API_KEY! } });
const { data: stream } = await res.json();
for (const d of stream.destinations) console.log(d.label, d.status, d.watchUrl ?? d.error);

Response

Response 200

{
  "data": {
    "id": "c0ffee00-1234-4abc-9def-0123456789ab",
    "title": "Friday product demo",
    "status": "live",
    "source": { "type": "url", "url": "https://cdn.example.com/live/index.m3u8", "mediaId": null, "filename": null, "kind": "hls" },
    "loop": false,
    "video": "auto",
    "maxDurationMinutes": null,
    "scheduledFor": "2026-11-06T12:30:00.000Z",
    "startedAt": "2026-11-06T12:30:07.512Z",
    "endedAt": null,
    "durationSeconds": 1834,
    "error": null,
    "stats": { "sourceKind": "hls", "videoCodec": "h264", "audioCodec": "aac", "width": 1920, "height": 1080, "fps": 30, "encoding": "copy", "bitrateKbps": 5120, "speed": 1, "restarts": 0 },
    "destinations": [
      { "id": "0a1b…", "kind": "youtube", "platform": "youtube", "label": "YouTube · Acme", "status": "live", "error": null, "watchUrl": "https://www.youtube.com/watch?v=AbCdEf12345", "server": null },
      { "id": "9f8e…", "kind": "twitch", "platform": "twitch", "label": "Twitch · acme", "status": "live", "error": null, "watchUrl": "https://www.twitch.tv/acme", "server": null },
      { "id": "4e5f…", "kind": "custom", "platform": "instagram", "label": "Instagram Live", "status": "failed", "error": "the platform closed the connection (check the stream key)", "watchUrl": null, "server": "rtmps://edgetee-upload-xx.fbcdn.net:443/rtmp" }
    ],
    "createdAt": "2026-11-05T09:12:44.120Z"
  }
}

(Some destination fields are omitted above for brevity.)

Stream fields

Field	Type	Description
`status`	string	`scheduled`, `starting`, `live`, `ending`, `ended`, `failed` or `canceled`.
`source.kind`	string	`hls`, `dash`, `file`, `rtmp`, `rtsp`, `srt` or `http`.
`startedAt`	string \| null	When media first reached a platform.
`durationSeconds`	integer	Seconds streamed so far (counted against live minutes).
`error`	string \| null	Why the stream failed, or why it ended early.
`stats`	object	What the source contained and how it was sent. `encoding` is `copy` (passed through) or the output height, such as `720p`.

Destination fields

Field	Type	Description
`kind`	string	`youtube`, `facebook`, `twitch` or `custom`.
`platform`	string	The platform (for custom destinations, from the preset).
`server`	string \| null	Custom destinations: the server address, without the stream key.
`status`	string	`pending`, `connecting`, `live`, `ended` or `failed`.
`error`	string \| null	Why this destination failed. Other destinations aren't affected.
`watchUrl`	string \| null	Public URL of the broadcast (YouTube, Facebook, Twitch).

Errors

Status	Code	When
401	`unauthorized`	Missing or invalid API key.
404	`not_found`	No live stream with this ID in the API key's project.

This page is also available as Markdown.