Skip to main content

Stream reports

List online live streams

Lists the online live streams under the specified entry point.

HTTP request


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/reports/online_streams

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

streamList: JSON Array. The list of online live streams. Each live stream corresponds to a JSON Object, and contains the following fields:

FieldTypeDescription
nameStringThe stream name.
startTimeStringThe time when stream pushing starts, in the RFC3339 format, for example, "2019-01-07T12:00:00Z".

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/live/reports/online_streams HTTP/1.1

Response line


_1
HTTP/1.1 200 OK

Request body


_12
{
_12
"streamList": [
_12
{
_12
"name": "{your_stream_name_1}",
_12
"startTime": "2021-11-29T19:00:00+08:00"
_12
},
_12
{
_12
"name": "{your_stream_name_2}",
_12
"startTime": "2021-11-29T19:00:00+08:00"
_12
},
_12
]
_12
}

Query information about an online live stream

Retrieves the information about the specified online live stream.

HTTP request


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/reports/online_streams/{stream_name}

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.
stream_nameStringRequired. The name of the live stream.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

  • startTime: String. The time when stream pushing starts, in the RFC3339 format, for example, "2019-01-07T12:00:00Z".

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/live/reports/online_streams/{stream_name} HTTP/1.1

Response line


_1
HTTP/1.1 200 OK

Request body


_3
{
_3
"startTime": "2021-10-11T04:08:52Z"
_3
}

Get stream-pushing records

Retrieves the stream-pushing records of a live stream within a specific time range. Only records for live streams that have ended can be retrieved.

The stream-pushing records have a delay of about two hours. You can only retrieve the records for the last 60 days. You can query any stream-pushing records generated within the last 60 days, but the time range to query at any one time cannot exceed 30 days.

HTTP request


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/reports/publish_history?start_time={start_time}&end_time={end_time}&stream_name={stream_name}

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.

Query parameters

ParameterTypeDescription
start_timeStringOptional. The starting point of the time range to query stream-pushing records, in the URL-encoded RFC3339 format. For example, 2019-01-07T12:00:00+08:00 corresponds to 2019-01-07T12%3A00%3A00%2B08%3A00. This parameter cannot be set earlier than 60 days before the current time.
end_timeStringOptional. The end point of the time range to query stream-pushing records, in the URL-encoded RFC3339 format. For example, 2019-01-07T12:00:00+08:00 corresponds to 2019-01-07T12%3A00%3A00%2B08%3A00. This parameter cannot be set later than the current time.
stream_nameStringRequired. The name of the live stream.
If the start_time and end_time parameters are not specified, the default time range to query stream-pushing records is the last 7 days.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

publishHistory: JSON Array. The list of the stream-pushing records, in the descending order of the time when each stream ended pushing. Each stream-pushing record corresponds to a JSON Object and contains the following fields:

FieldTypeDescription
nameStringThe stream name.
startTimeStringThe start time of the stream pushing in the RFC3339 format, for example "2019-01-07T12:00:00+08:00".
endTimeStringThe end time of the stream pushing in the RFC3339 format, for example "2019-01-07T12:00:00+08:00".
durationIntegerThe duration of the stream pushing in seconds.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/live/reports/publish_history?start_time={start_time}&end_time={end_time}&stream_name={stream_name} HTTP/1.1

Response line


_1
HTTP/1.1 200 OK

Request body


_16
{
_16
"publishHistory": [
_16
{
_16
"name": "{your_stream_name_1}",
_16
"startTime": "2021-08-25T12:19:23+08:00",
_16
"endTime": "2021-08-25T14:42:58+08:00",
_16
"duration": 8616
_16
},
_16
{
_16
"name": "{your_stream_name_2}",
_16
"startTime": "2021-08-25T10:44:40+08:00",
_16
"endTime": "2021-08-25T11:01:49+08:00",
_16
"duration": 1030
_16
}
_16
]
_16
}

Get stream-pushing quality statistics

Retrieves the stream-pushing quality statistics of a live stream within a specific time range.

The stream-pushing quality statistics have a delay of about three minutes. You can query any stream-pushing records generated within the last six days, but the time range to query at any one time cannot exceed six hours.

HTTP request


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/reports/publish_quality?start_time={start_time}&end_time={end_time}&stream_name={stream_name}

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.

Query parameters

ParameterTypeDescription
start_timeStringOptional. The starting point of the time range to query stream-pushing quality, in the URL-encoded RFC3339 format. For example, 2019-01-07T12:00:00+08:00 corresponds to 2019-01-07T12%3A00%3A00%2B08%3A00. This parameter cannot be set earlier than 60 days before the current time.
end_timeStringOptional. The end point of the time range to query stream-pushing quality, in the URL-encoded RFC3339 format. For example, 2019-01-07T12:00:00+08:00 corresponds to 2019-01-07T12%3A00%3A00%2B08%3A00. This parameter cannot be set later than the current time.
stream_nameStringRequired. The name of the live stream.
If the start_time and end_time parameters are not specified, the default time range to query stream-pushing quality is the last 6 hours.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

publishHistory: JSON Array. The list of the stream-pushing quality statistics, from the latest to the earliest. Each stream-pushing record corresponds to a JSON Object and contains the following fields:

FieldTypeDescription
nameStringThe stream name.
timeStringThe time when the stream-pushing quality statistics were generated, in the RFC3339 format, for example, "2019-01-07T12:00:00+08:00". The stream-pushing quality statistics are calculated in intervals of one minute.
bitrateIntegerThe stream-pushing bitrate (bps).
frameRateIntegerThe stream-pushing frame rate (fps).
cdnIpStringThe IP address of the CDN node to push the stream to.
clientIpStringThe IP address of the client pushing the stream.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/live/reports/publish_quality?start_time={start_time}&end_time={end_time}&stream_name={stream_name} HTTP/1.1

Response line


_1
HTTP/1.1 200 OK

Request body


_20
{
_20
"QualityHistory": [
_20
{
_20
"name": "{your_stream_name}",
_20
"time": "2021-08-25T12:19:00+08:00",
_20
"bitrate": 1123388,
_20
"framerate": 31,
_20
"cdnIp": "58.220.74.80",
_20
"clientIp": "218.19.252.82"
_20
},
_20
{
_20
"name": "{your_stream_name}",
_20
"time": "2021-08-25T12:18:00+08:00",
_20
"bitrate": 1177908,
_20
"framerate": 30,
_20
"cdnIp": "58.220.74.80",
_20
"clientIp": "218.19.252.82"
_20
}
_20
]
_20
}

Get stream-playing statistics

Retrieves the stream-playing statistics of a live stream within a specific time range.

The stream-playing statistics have a delay of about three minutes. You can query any stream-playing records within the last 30 days, but the time range to query at any one time cannot exceed two hours.

HTTP request


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/reports/stream_play_statistic?start_time={start_time}&end_time={end_time}&stream_name={stream_name}

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.

Query parameters

ParameterTypeDescription
start_timeStringOptional. The starting point of the time range to query stream-playing statistics, in the URL-encoded RFC3339 format. For example, 2019-01-07T12:00:00+08:00 corresponds to 2019-01-07T12%3A00%3A00%2B08%3A00. This parameter cannot be set earlier than 30 days before the current time.
end_timeStringOptional. The end point of the time range to query stream-playing statistics, in the URL-encoded RFC3339 format. For example, 2019-01-07T12:00:00+08:00 corresponds to 2019-01-07T12%3A00%3A00%2B08%3A00. This parameter cannot be set later than the current time.
stream_nameStringRequired. The name of the live stream.
If the start_time and end_time parameters are not specified, the default time range to query stream-playing statistics is the last 2 hours.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

playStatistic: JSON Array. The list of the stream-playing statistics, from the latest to the earliest. Each stream-pushing record corresponds to a JSON Object and contains the following fields:

FieldTypeDescription
nameStringThe stream name.
timeStringThe time when the stream-playing statistics were generated, in the RFC3339 format, for example, "2019-01-07T12:00:00+08:00". The stream-playing statistics are calculated in intervals of one minute.
linkNumIntegerThe number of connections, that is, the number of clients playing the stream.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/live/reports/stream_play_statistic?start_time={start_time}&end_time={end_time}&stream_name={stream_name} HTTP/1.1

Response line


_1
HTTP/1.1 200 OK

Request body


_14
{
_14
"playStatistic": [
_14
{
_14
"name": "{your_stream_name}",
_14
"time": "2021-08-25T12:19:00+08:00",
_14
"linkNum": 3
_14
},
_14
{
_14
"name": "{your_stream_name}",
_14
"time": "2021-08-25T12:18:00+08:00",
_14
"linkNum": 5
_14
}
_14
]
_14
}

HTTP status codes

Status codeDescription
200The request succeeds.
400The parameter is invalid, for example the appid or the entry_point is empty, or the region parameter value is invalid.
401Unauthorized (the customer ID and the customer secret do not match).
404The server cannot find the resource according to the request, which means the requested entry point does not exist or the requested URI path is invalid.
500An internal error occurs in the server, so the server is not able to complete the request.
504An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.