Stream reports

List online live streams

Lists the online live streams under the specified entry point.

HTTP request

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

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. 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:

Field	Type	Description
`name`	String	The stream name.
`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

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

Response line

HTTP/1.1 200 OK

Request body

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

Query information about an online live stream

Retrieves the information about the specified online live stream.

HTTP request

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

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.
`stream_name`	String	Required. 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

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

Response line

HTTP/1.1 200 OK

Request body

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

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

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

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

Query parameters

Parameter	Type	Description
`start_time`	String	Optional. 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_time`	String	Optional. 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_name`	String	Required. 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:

Field	Type	Description
`name`	String	The stream name.
`startTime`	String	The start time of the stream pushing in the RFC3339 format, for example `"2019-01-07T12:00:00+08:00"`.
`endTime`	String	The end time of the stream pushing in the RFC3339 format, for example `"2019-01-07T12:00:00+08:00"`.
`duration`	Integer	The 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

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

HTTP/1.1 200 OK

Request body

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

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

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

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

Query parameters

Parameter	Type	Description
`start_time`	String	Optional. 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_time`	String	Optional. 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_name`	String	Required. 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:

Field	Type	Description
`name`	String	The stream name.
`time`	String	The 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.
`bitrate`	Integer	The stream-pushing bitrate (bps).
`frameRate`	Integer	The stream-pushing frame rate (fps).
`cdnIp`	String	The IP address of the CDN node to push the stream to.
`clientIp`	String	The 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

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

HTTP/1.1 200 OK

Request body

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

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

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

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

Query parameters

Parameter	Type	Description
`start_time`	String	Optional. 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_time`	String	Optional. 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_name`	String	Required. 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:

Field	Type	Description
`name`	String	The stream name.
`time`	String	The 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.
`linkNum`	Integer	The 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

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

HTTP/1.1 200 OK

Request body

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

HTTP status codes

Status code	Description
200	The request succeeds.
400	The parameter is invalid, for example the `appid` or the `entry_point` is empty, or the `region` parameter value is invalid.
401	Unauthorized (the customer ID and the customer secret do not match).
404	The 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.
500	An internal error occurs in the server, so the server is not able to complete the request.
504	An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.