# Get a live stream

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


```http
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

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

```ts tab="Node.js"
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

```json title="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. |