Live Platform API v1
Live Platform API
Live
Platform API
Home
/
Live
/
Platform API
/
Live

Retrieve a list of live events

Retrieves a list of live events. Only ongoing live events can be retrieved.


HTTP request

GET https://api-{application_id}.calls.sendbird.com/v1/live-events

Parameters

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

host_type

string

Restricts the search scope to only retrieve live events whose host_type matches any of the specified values. An acceptable value is single_host.

state

string

Restricts the search scope to only retrieve live events whose state matches any of the specified values. Acceptable values are the following:
- created: Indicates the live event is created and the host can enter. The host can stream media.
- ready: Indicates the live event is ready to get started and participants can enter and chat with the host. The host can stream media but participants can’t receive it.
- ongoing : Indicates the live event is ongoing and participants can receive media streaming of the host and chat.
- ended : Indicates the live event has ended.

created_at_start_date

int

Specifies the value of time period to restrict the search scope to only retrieve live events whose created_at is equal to or greater than the specified value, in Unix milliseconds.

created_at_end_date

int

Specifies the value of time period to restrict the search scope to only retrieve live events whose created_at is less than the specified value, in Unix milliseconds.

started_at_start_date

int

Specifies the value of time period to restrict the search scope to only retrieve live events where the live event's started_at is equal to or greater than the specified value, in Unix milliseconds.

started_at_end_date

int

Specifies the value of time period to restrict the search scope to only retrieve live events where the live event's started_at is less than the specified value, in Unix milliseconds.

participant_count_range_gte

int

Specifies the number of current participants to restrict the search scope to only retrieve live events where the number of participants is equal to or greater than the specified value.

participant_count_range_lte

int

Specifies the number of current participants to restrict the search scope to only retrieve live events where the number of participants is equal to or less than the specified value.

live_event_ids

string

Searches for live events which the specified live event IDs are included in the parameter value. The string should consist of multiple URL encoded live event IDs separated by commas.

The live_event_id can be used interchangeably with this parameter, but can only specify one live ID. When both live_event_id and live_event_ids are specified, an error will be returned. The maximum number of live IDs in a single request is 10.

created_by_user_ids

string

Searches for live events which the specified user IDs of users who created live events are included in the parameter value. The string should consist of multiple URL encoded user IDs separated by commas.
-The created_by_user_id can be used interchangeably with this parameter, but can only specify one user ID. When both created_by_user_id and created_by_user_ids are specified, an error will be returned.
-The maximum number of user IDs in a single request is 10.

duration_range_gte

long

Specifies the value of the duration to restrict search scope to only retrieve live events whose duration is equal to or greater than the specified value, in Unix milliseconds.

duration_range_lte

long

Specifies the value of the duration to restrict search scope to only retrieve live events whose duration is less than the specified value, in Unix milliseconds.

title_contains

string

Searches for live events which contains the specified value in their live event titles.

current_host_user_id

string

Searches for a live event where the specified user ID of user who has entered as host is equal to the parameter value.

limit

int

Specifies the number of results to retrieve per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

prev

string

Specifies the value of the prev property in the response to retrieve the previous page in the result set.

next

string

Specifies the value of the next property in the response to retrieve the next page in the result set.


Response

If successful, this action returns a list of all live events in the application in the response body.

{
    "live_events": [
        {
            "created_at": 1657690472593,
            "created_by": "",
            "cumulative_participant_count": 0,
            "custom_items": {},
            "duration": 0,
            "ended_at": 1657690472579,
            "ended_by": "",
            "host": none,
            "host_type": "single_host",
            "is_host_streaming": false,
            "live_event_id": "bbecbb12-6756-4421-a80b-68cdffabe6bc",
            "participant_count": 0,
            "peak_participant_count": 0,
            "set_ready_at": none,
            "set_ready_by": "",
            "started_at": 1657690472579,
            "started_by": "",
            "state": "ended",
            "user_ids_for_host": none,
        },
        ... # More live events
    ],
    "next": "LWs1OQJJV1FeRxtSDwALfjQwZ2gCXgwHUElWQx1HQwNnazg",
    "prev": none,
}

List of response properties

Property nameTypeDescription

live_events

list of nested objects

A list of live events that has been retrieved.

prev

string

Specifies the value of the prev property in the response to retrieve the previous page in the result set.

next

string

Specifies the value of the next property in the response to retrieve the next page in the result set.