Documentation
Cloud Recording
API Documents
Recording Status Check

Query recording status

Last updated：2024-10-17 15:02

Description

Queries the status of a recording task that started within 3 days before this method is called.

Request method and endpoint

Request method: POST
Request endpoint: https://cloudrecord-api.zego.im/?Action=DescribeRecordStatus
Transmission protocol: HTTPS
Rate limit: 10 requests/second

Request parameters

Listed below are the parameters specific to this request. For the list of public request parameters, see Accessing Server APIs - Public parameters.

Parameter	Type	Required	Description
TaskId	Int	Yes	Task ID. The value is a 16-byte character string.

Sample request

The following is a request example of the DescribeRecordStatus method:

Request URL

https://cloudrecord-api.zego.im/?Action=DescribeRecordStatus
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0

Request message body
```
{
  "TaskId": "X3CgNeE4I1qAAABN"
}
```

Response parameters

Parameter	Type	Description
Code	Int64	Return code.
Message	String	Description of the request execution result.
RequestId	String	Request ID.
Data	Object	Response object. For details, see Data member parameters.

Listed below are Data member parameters.

Parameter	Type	Description
RoomId	String	Room ID.
RecordMode	Int	For details, see Start recording.
StreamType	Int	For details, see Start recording.
RecordBeginTimestamp	Int64	Recording start time, in ms. The value is a Unix timestamp.
RecordEndTimestamp	Int64	Recording end time, in ms. The value is a Unix timestamp.
Status	Int	Recording status. 1: initialized 2: ongoing 3: completed 4: ended abnormally 5: paused
RecordFiles	Array of Object	File information. For details, see RecordFiles member parameters. If the video snapshotting function is used, this parameter will not be returned.

For a recording task in completed state, if no streaming is initiated in the room during the recording, no recording file will be generated and the RecordFiles parameter will not be returned.

Listed below are RecordFiles member parameters.

Parameter	Type	Description
UserId	String	ID of the user who initiates streaming. In mixed-stream recording mode, the value is the same as that of `MixOutputStreamId`.
UserName	String	Nickname of the user who initiates streaming. In mixed-stream recording mode, the value is the same as that of `MixOutputStreamId`.
StreamId	String	ID of the recorded stream. In mixed-stream recording mode, the value is the same as that of `MixOutputStreamId`.
FileId	String	File ID. For details, see the `OutputFileRule` parameter in Start recording.
VideoId	String	Video ID received after a recording file is successfully uploaded to Alibaba Cloud VOD or Tencent Cloud VOD platform. For Alibaba Cloud VOD, the value maps `VideoId`. For Tencent Cloud VOD, the value maps `FileId`.
FileUrl	String	File access URL. This parameter is not returned when the third-party cloud storage platform of Qiniu Cloud or Alibaba Cloud VOD is used.
OutputFileFormat	String	Format of the output recording file. The options are `mp4`, `flv`, `hls`, `jpg`, and `aac`.
FileSize	Int64	File size, in bytes.
Duration	Int	Recording duration, in ms.
ResolutionWidth	Int	Resolution width of a video, in pixels.
ResolutionHeight	Int	Resolution height of a video, in pixels.
MediaTrackType	Int	Media type of a recording file. 1: audio only 2: video only 3: audio and video
BeginTimestamp	Int64	Unix timestamp when a new stream signal is received in a room, in ms.
CustomBeginTimestamp	Int64	Customized timestamp. This timestamp is carried in the stream SEI information, and is extracted from SEI through the specified protocol.
Status	Int	File status. 1: being recorded 2: being uploaded to the specified cloud storage platform 3: successfully uploaded to the specified cloud storage platform 4: failed to be uploaded to the specified cloud storage platform but successfully uploaded to ZEGOCLOUD's backup cloud storage platform 5: failed to be uploaded either to the specified cloud storage platform or ZEGOCLOUD's backup cloud storage platform

Sample response

The following is a response example of the DescribeRecordStatus method:

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123",
    "Data": {
        "RoomId": "xxxx",
        "RecordMode": 2,
        "StreamType": 3,
        "RecordBeginTimestamp": 1601221452099,
        "RecordEndTimestamp": 1601221508795,
        "Status": 3,
        "RecordFiles": [
            {
                "UserId": "my_out",
                "UserName": "my_out",
                "StreamId": "my_out",
                "FileId": "X3CgNeE4I1qAAABN_xxxx_my_out_VA_20200927154419775.mp4",
                "VideoId": "820e50e52e0a490caf44eec8aec527a7",
                "OutputFileFormat": "mp4",
                "FileSize": 432643544,
                "Duration": 33874,
                "ResolutionWidth": 1920,
                "ResolutionHeight": 1080,
                "MediaTrackType": 3,
                "BeginTimestamp": 1601221459830,
                "CustomBeginTimestamp": 0,
                "Status": 3,
                "FileUrl": "https://xxxx.oss-cn-shanghai.aliyuncs.com/record/X3CgNeE4I1qAAABN_xxxx_my_out_VA_20200927154419775.mp4"
            }
        ]
    }
}