> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Stream Status
> Retrieve the current status of a stream, including source details and the state and URLs of every output.
## Overview
Returns the current state of a stream. The response shape is the same whether
the stream is scheduled, live, or finished, which makes it suitable for
dashboards and polling loops.
Use it to:
* Track the stream through its lifecycle (`scheduled` → `setting up` →
`started` → `ended`).
* Read the playback URLs of Camb.ai-hosted outputs (SRT listener, HLS
recording).
* Check per-target delivery state and surface errors.
When polling, a cadence of 5–15 seconds is plenty. Back off once the stream
reaches a terminal status (`4`, `5`, or `6`).
```bash cURL theme={null}
curl -X GET "https://client.camb.ai/apis/stream/1234" \
-H "x-api-key: YOUR_API_KEY"
```
```python Python theme={null}
import requests
response = requests.get(
"https://client.camb.ai/apis/stream/1234",
headers={"x-api-key": "YOUR_API_KEY"},
)
response.raise_for_status()
print(response.json())
```
```json Response theme={null}
{
"stream_id": 1234,
"status": 3,
"source": {
"type": 1,
"playback_url": null
},
"targets": [
{
"id": "spanish-out",
"type": 1,
"state": "active",
"playback_url": null,
"destination_url": "srt://delivery.example.com:9100"
}
],
"scheduled_at": "2026-08-01T10:00:00Z",
"started_at": "2026-08-01T10:00:05Z",
"stopped_at": null,
"task_id": "b8f2f1f0-3c6a-4f5e-9b2a-1c2d3e4f5a6b",
"error": null
}
```
## Reading the response
* `status` - the stream lifecycle status: `1` scheduled, `2` setting up, `3`
started, `4` ended, `5` interrupted, `6` error.
* `targets[].state` - each output progresses `scheduled` → `active` →
`completed`, or `failed` on error.
* `targets[].playback_url` - set for Camb.ai-hosted outputs; this is where
you or your viewers connect.
* `targets[].destination_url` - set for push outputs; the endpoint Camb.ai is
delivering to.
* `error` - populated when `status` is `6`.
## Errors
* `404` - No stream with this ID belongs to your team.
* `422` - Invalid `stream_id`.
## Related endpoints
* [Create a Stream](create-new-stream)
* [Update a Stream](update-stream)
* [Delete a Stream](delete-stream)
## OpenAPI
````yaml get /stream/{stream_id}
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://client.camb.ai/apis
security: []
paths:
/stream/{stream_id}:
get:
tags:
- Apis
- Streaming
summary: Get Stream Status
description: >-
Retrieve the current status of a stream, including source connection
details and the state and URLs of every output.
operationId: get_stream_result_stream__stream_id__get
parameters:
- name: stream_id
in: path
required: true
schema:
type: integer
title: Stream Id
description: Identifier returned when the stream was created.
responses:
'200':
description: Current state of the stream.
content:
application/json:
schema:
$ref: '#/components/schemas/StreamView'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
StreamView:
type: object
title: StreamView
description: >-
Current state of a stream. The shape is identical whether the stream is
scheduled, live, or finished.
properties:
stream_id:
type: integer
title: Stream ID
status:
$ref: '#/components/schemas/StreamStatus'
description: Lifecycle status.
source:
anyOf:
- $ref: '#/components/schemas/SourceView'
- type: 'null'
description: Source connection details.
targets:
type: array
items:
$ref: '#/components/schemas/TargetView'
title: Targets
default: []
description: State and URLs of each output.
scheduled_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Scheduled At
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
stopped_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Stopped At
task_id:
anyOf:
- type: string
- type: 'null'
title: Task ID
description: Setup task identifier.
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Failure description when `status` is `6` (error).
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
StreamStatus:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
title: StreamStatus
description: |-
Lifecycle status of a stream.
| Value | Status | Description |
|---|---|---|
| `1` | Scheduled | Created and waiting for its start time. |
| `2` | Setting up | Resources are being provisioned. |
| `3` | Started | Live and processing. |
| `4` | Ended | Completed normally. |
| `5` | Interrupted | Stopped before its scheduled end. |
| `6` | Error | Failed; see the `error` field. |
SourceView:
type: object
title: SourceView
properties:
type:
anyOf:
- $ref: '#/components/schemas/StreamType'
- type: 'null'
description: >-
Best-effort protocol of the source, inferred from its URL. May be
`null`.
playback_url:
anyOf:
- type: string
- type: 'null'
title: Playback URL
description: URL where the source can be played back, when available.
TargetView:
type: object
title: TargetView
properties:
id:
type: string
title: ID
description: Target identifier from the create payload.
type:
$ref: '#/components/schemas/StreamType'
description: Output protocol/type.
state:
type: string
enum:
- scheduled
- deferred
- active
- completed
- failed
title: State
description: Lifecycle state of this target output.
playback_url:
anyOf:
- type: string
- type: 'null'
title: Playback URL
description: URL to play this output, for Camb.ai-hosted outputs.
destination_url:
anyOf:
- type: string
- type: 'null'
title: Destination URL
description: URL this output is being pushed to, for push-type targets.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
StreamType:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
title: StreamType
description: >-
Protocol/type of a target stream.
| Value | Type | Description |
|---|---|---|
| `1` | SRT caller | Push output to your SRT endpoint (Camb.ai connects
out to `url`). |
| `2` | RTMP | Push output to an RTMP ingest `url`. |
| `3` | HLS recording | Camb.ai-hosted HLS output; `url` and `inputs`
are auto-assigned, and the playback URL is returned. |
| `4` | YouTube RTMP | Push directly to a YouTube RTMP ingest URL. |
| `5` | YouTube HLS | Push directly to a YouTube HLS ingest URL. |
| `6` | SRT listener | Camb.ai hosts an SRT endpoint that you (or your
player) pull from; `url` is auto-assigned and returned. |
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
description: >-
The `x-api-key` is a custom header required for authenticating requests
to our API. Include this header in your request with the appropriate API
key value to securely access our endpoints. You can find your API key(s)
in the 'API' section of our studio website.
````