This article contains detailed help for the Cloud Recording RESTful APIs.

Before proceeding, we recommend you take a quick look at the key features of Cloud Recording.

• Individual recording: Records the audio and video of each UID in separate files, and uploads the recorded files to a third-party cloud storage service.
• Composite recording: Records the audio and video of multiple UIDs in a single file, and uploads the recorded file to a third-party cloud storage service.
• Capture screenshots: In individual recording mode, takes screenshots of the video stream and uploads the screenshots to a third-party cloud storage service.
• Web page recording: Records the content and the audio of a specified web page in a single file, and uploads the recorded file to a third-party cloud storage service.

Authentication

The RESTful APIs only support HTTPS. Before using the Agora RESTful API, you need to pass the basic HTTP authentication.

Data format

All requests are sent to the host: api.agora.io.

• Request: See the examples in the following APIs.
• Response: The response content is in JSON format.

Call sequence

Use the RESTful APIs in the following steps:

1. Call the acquire method to request a resource ID for cloud recording.
2. Call the start method within five minutes after getting the resource ID to start the recording.
3. Call the stop method to stop the recording.

During the recording, you can call the query method to check the recording status.

Get a resource ID

Before starting a cloud recording, you need to call acquire to get a resource ID.

Each resource ID can only be used for one recording session.

• Method:POST
• Endpoint: /v1/apps/<appid>/cloud_recording/acquire

The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you want to raise the limit.

If this method call succeeds, you get a resource ID (resourceId) from the HTTP response body. The resource ID is valid for five minutes, so you need to start recording with this resource ID with it before it expires.

Parameters

The following parameter is required in the URL.

The following parameters are required in the request body.

An HTTP request example of acquire

• The request URL is https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire.
• Content-type is application/json;charset=utf-8.
• Authorization is the basic authentication, see RESTful API authentication for details.
• The request body:

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest":{
      "resourceExpiredHour":  24
   }
}

A response example of acquire

"Code": 200,
"Body":
{
 "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}

• code: Number. Status code.
• resourceId: String. The resource ID for cloud recording. The resource ID is valid for five minutes.

Start cloud recording

After getting a resource ID, call start to begin cloud recording. The Cloud Recording service does the following after you call start:

1. Subscribes to the audio and video streams in the channel according to recordingConfig.
2. Processes the subscribed media streams, such as generating recorded files in the specified file format, taking video screenshots, or uploading recorded files to an extension service.
3. Uploads the recorded files or screenshots to your third-party cloud storage according to storageConfig.

The HTTP method and endpoint of start:

• Method: POST
• Endpoint: /v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start

The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you need to raise the limit.

Parameters

The following parameters are required in the URL.

The following parameters are required in the request body.

Recording configuration

recordingConfig is a JSON object for configuring how the Cloud Recording service subscribes to the media streams in the channel. recordingConfig has the following fields:

• channelType: Number. The channel profile. Agora Cloud Recording must use the same channel profile as the Agora RTC SDK. Otherwise, issues may occur.
  • 0: (Default) Communication profile.
  • 1: Live broadcast profile.
• streamTypes: (Optional) Number. The type of the media stream to subscribe to:
  • 0: Subscribes to audio streams only.
  • 1: Subscribes to video streams only.
  • 2: (Default) Subscribes to both audio and video streams.
• decryptionMode: (Optional) Number. The decryption mode that is the same as the encryption mode set by the Agora Native/Web SDK. When the channel is encrypted, Agora Cloud Recording uses decryptionMode to enable the built-in decryption function.
• secret: (Optional) String. The decryption password when decryption mode is enabled.
• audioProfile: (Optional) Number. The profile of the output audio stream, including the sample rate, bitrate, encoding mode, and the number of channels. You cannot set this parameter in individual recording mode.
  • 0: (Default) Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.
  • 1: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
  • 2: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.
• videoStreamType: (Optional) Number. The type of the video stream to subscribe to.
  • 0: (Default) Subscribes to the high-quality stream.
  • 1: Subscribes to the low-quality stream.
• maxIdleTime: (Optional) Number. Agora Cloud Recording automatically stops recording and leaves the channel when there is no user in the recording channel after a time period (30 seconds by default) set by this parameter. The value range is from 5 to 2,592,000 (30 days). Once the recording stops, the recording service generates new recorded files if you call start for the second time.

• transcodingConfig: (Optional) JSON. The video transcoding configuration. You cannot set this parameter in individual recording mode. If you set this parameter, ensure that you set width, height, fps, and bitrate. Refer to Set the Video Profile for detailed information about setting transcodingConfig.

  • width: (Mandatory) Number. The width of the mixed video (pixels). The default value is 360. width should not exceed 1920, and width*height should not exceed 1920 * 1080; otherwise, an error occurs.
  • height: (Mandatory) Number. The height of the mixed video (pixels). The default value is 640. height should not exceed 1920, and width*height should not exceed 1920 * 1080; otherwise, an error occurs.
  • fps: (Mandatory) Number. The video frame rate (fps). The default value is 15.
  • bitrate: (Mandatory) Number. The video bitrate (Kbps). The default value is 500.
  • maxResolutionUid: (Optional) String. When mixedVideoLayout is set as 2 (vertical layout), you can specify the UID of the large video window by this parameter.
  • backgroundColor: (Optional) String. The background color of the canvas (the display window or screen) in RGB hex value. The string starts with a "#". The default value is "#000000", the black color.
  • mixedVideoLayout: (Optional) Number. The video mixing layout. 0, 1, and 2 are the predefined layouts. If you set this parameter as 3, you need to set the layout by the layoutConfig parameter.
    • 0: (Default) Floating layout. The first user in the channel occupies the full canvas. The other users occupy the small regions on top of the canvas, starting from the bottom left corner. The small regions are arranged in the order of the users joining the channel. This layout supports one full-size region and up to four rows of small regions on top with four regions per row, comprising 17 users.
    • 1: Best fit layout. This is a grid layout. The number of columns and rows and the grid size vary depending on the number of users in the channel. This layout supports up to 17 users.
    • 2: Vertical layout. One large region is displayed on the left edge of the canvas, and several smaller regions are displayed along the right edge of the canvas. The space on the right supports up to 2 columns of small regions with 8 regions per column. This layout supports up to 17 users.
    • 3: Customized layout. Set the layoutConfig parameter to customize the layout.
  • layoutConfig: (Optional) JSONArray. An array of the configuration of each user's region. Supports 17 users at most. Each user's region configuration is a JSON object with the following parameters:
    • uid: (Optional) String. The string contains the UID of the user displaying the video in the region. If this parameter is not specified, the configurations apply in the order of the users joining the channel.
    • x_axis: (Mandatory) Float. The relative horizontal position of the top-left corner of the region. The value is between 0.0 (leftmost) and 1.0 (rightmost), and is accurate to six decimal places.
    • y_axis: (Mandatory) Float. The relative vertical position of the top-left corner of the region. The value is between 0.0 (top) and 1.0 (bottom), and is accurate to six decimal places.
    • width: (Mandatory) Float. The relative width of the region. The value is between 0.0 and 1.0, and is accurate to six decimal places.
    • height: (Mandatory) Float. The relative height of the region. The value is between 0.0 and 1.0, and is accurate to six decimal places.
    • alpha: (Optional) Float. The transparency of the image. The value is between 0.0 (transparent) and 1.0 (opaque), and is accurate to six decimal places. The default value is 1.0.
    • render_mode: (Optional) Number. The video display mode:
      • 0: (Default) Cropped mode. Uniformly scales the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.
      • 1: Fit mode. Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.

• subscribeAudioUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you want to subscribe. If you want to subscribe to all UIDs, you do not need to set this parameter. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 1. See Set up subscription lists for details.

• unSubscribeAudioUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you do not want to subscribe. Once you set this parameter, the recording service subscribes to the audio of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 1. See Set up subscription lists for details.

• subscribeVideoUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you want to subscribe. If you want to subscribe to all UIDs, you do not need to set this parameter. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 0. See Set up subscription lists for details.

• unSubscribeVideoUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you do not want to subscribe. Once you set this parameter, the recording service subscribes to the video of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 0. See Set up subscription lists for details.

• subscribeUidGroup: (Optional) Number. The estimated maximum number of subscribed users. You must set this parameter in individual mode. For example, if subscribeVideoUids is ["100","101","102"] and subscribeAudioUids is ["101","102","103"], the number of subscribed users is 4.

  • 0: 1 to 2 UIDs
  • 1: 3 to 7 UIDs
  • 2: 8 to 12 UIDs
  • 3: 13 to 17 UIDs

Configurations for the recorded files

recordingFileConfig is a JSON Object for configuring recorded files. You cannot set both recordingFileConfig and snapshotConfig at the same time, otherwise an error will occur. recordingFileConfigincludes the following fields:

• avFileType: (Optional) JSONArray. An array of strings. Sets the format of the recorded files.
  • "hls": (Default) M3U8 and TS files.
  • "mp4": MP4 files. This value is for web page recording (web) only and must be set together with "hls"; otherwise, the recording service returns error code 2. When the length of the recorded file reaches two hours, or when the size of the file exceeds 2 GB, the recording service automatically creates another MP4 file.

Snapshot configuration

snapshotConfig is a JSON object for configuring how Cloud Recording takes screenshots. Pay attention to the following parameters, as incorrect settings result in errors or failure to capture screenshots.

• In the URL of your request, mode must be individual.
• You cannot set both recordingFileConfig and snapshotConfig at the same time.
• streamTypes must be 1 or 2.
• If you have set subscribeAudioUid, you must also set subscribeVideoUids.

snapshotConfig includes the following fields:

• captureInterval: (Optional) Integer. The time interval (in seconds) between two successive screenshots. captureInterval should be within the range [5, 3600]. The default value is 10.
• fileType: JSONArray. File format of the screenshots. fileType can only take ["jpg"], setting screenshots to the JPG format.

Cloud storage configuration

storageConfig is a JSON object that configures the third-party cloud storage with the following fields.

• vendor: Number. The third-party cloud storage vendor.

  • 0: Qiniu Cloud
  • 1: Amazon S3
  • 2: Alibaba Cloud
  • 3: Tencent Cloud
  • 4: Kingsoft Cloud

• region: Number. The regional information specified by the third-party cloud storage:
  When the third-party cloud storage is Qiniu Cloud (vendor = 0):

  • 0: East China
  • 1: North China
  • 2: South China
  • 3: North America
  • 4: Southeast Asia

  When the third-party cloud storage is Amazon S3 (vendor = 1):

  • 0: US_EAST_1
  • 1: US_EAST_2
  • 2: US_WEST_1
  • 3: US_WEST_2
  • 4: EU_WEST_1
  • 5: EU_WEST_2
  • 6: EU_WEST_3
  • 7: EU_CENTRAL_1
  • 8: AP_SOUTHEAST_1
  • 9: AP_SOUTHEAST_2
  • 10: AP_NORTHEAST_1
  • 11: AP_NORTHEAST_2
  • 12: SA_EAST_1
  • 13: CA_CENTRAL_1
  • 14: AP_SOUTH_1
  • 15: CN_NORTH_1
  • 16: CN_NORTHWEST_1
  • 17: US_GOV_WEST_1

  When the third-party cloud storage is Alibaba Cloud (vendor = 2):

  • 0: CN_Hangzhou
  • 1: CN_Shanghai
  • 2: CN_Qingdao
  • 3: CN_Beijing
  • 4: CN_Zhangjiakou
  • 5: CN_Huhehaote
  • 6: CN_Shenzhen
  • 7: CN_Hongkong
  • 8: US_West_1
  • 9: US_East_1
  • 10: AP_Southeast_1
  • 11: AP_Southeast_2
  • 12: AP_Southeast_3
  • 13: AP_Southeast_5
  • 14: AP_Northeast_1
  • 15: AP_South_1
  • 16: EU_Central_1
  • 17: EU_West_1
  • 18: EU_East_1

  When the third-party cloud storage is Tencent Cloud (vendor = 3):

  • 0：AP_Beijing_1
  • 1：AP_Beijing
  • 2：AP_Shanghai
  • 3：AP_Guangzhou
  • 4：AP_Chengdu
  • 5：AP_Chongqing
  • 6：AP_Shenzhen_FSI
  • 7：AP_Shanghai_FSI
  • 8：AP_Beijing_FSI
  • 9：AP_Hongkong
  • 10：AP_Singapore
  • 11：AP_Mumbai
  • 12：AP_Seoul
  • 13：AP_Bangkok
  • 14：AP_Tokyo
  • 15：NA_Siliconvalley
  • 16：NA_Ashburn
  • 17：NA_Toronto
  • 18：EU_Frankfurt
  • 19：EU_Moscow

  When the third-party cloud storage is Kingsoft Cloud (vendor = 4):

  • 0：CN_Hangzhou
  • 1：CN_Shanghai
  • 2：CN_Qingdao
  • 3：CN_Beijing
  • 4：CN_Guangzhou
  • 5：CN_Hongkong
  • 6：JR_Beijing
  • 7：JR_Shanghai
  • 8：NA_Russia_1
  • 9：NA_Singapore_1

• bucket: String. The bucket of the third-party cloud storage.

• accessKey: String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.

• secretKey: String. The secret key of the third-party cloud storage.

• fileNamePrefix: (Optional) JSONArray. An array of strings. Sets the path of the recorded files in the third-party cloud storage. For example, if fileNamePrefix = ["directory1","directory2"], Agora Cloud Recording will add the prefix "directory1/directory2/" before the name of the recorded file, that is, directory1/directory2/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:

  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9

Extension service configuration

extensionServiceConfig is a JSON Object for extension service configurations. Extension services are a collection of applications that process the media streams generated from the Agora RTC SDK. One example extension service is VoD service.

extensionServiceConfig has the following fields:

• errorHandlePolicy: (Optional) String. Error handling policy. You can only set it to the default value, "error_abort", which means that once an error occurs to an extension service, all other non-extension services, such as stream subscription, also stop.

• apiVersion: (Optional) String. The version of the Cloud Recording RESTful API. The default value is "v1".

• extensionServices: JSONArray. An array of the configuration for each extension service.

  Currently you cannot configure more than one extension service per recording session.

  ApsaraVideo for VoD
  When using ApsaraVideo for VoD,extensionServicesextensionServices includes the following fields:

  • serviceName: String. The name of the extension service. To use ApsaraVideo for VoD, set it as "aliyun_vod_service".
    • errorHandlePolicy: (Optional) String. Error handling policy. You can only set it to the default value, "error_abort", which means that if an error occurs to the current extension service, other extension services also stop.
  • serviceParam: JSON. Configurations for an extension service. To use ApsaraVideo for VoD, configure as follows:
    • accessKey: String. Corresponds to the AccessKeyId in the AccessKey of Alibaba Cloud. For details, see Alibaba Cloud's documentation.
    • secretKey: String. Corresponds to the AccessKeySecret in the AccessKey of Alibaba Cloud. For details, see Alibaba Cloud's documentation.
    • regionId: String. The service region. For details, see Alibaba Cloud's documentation.
    • apiData: JSON. Configurations for ApsaraVideo for VoD.
      • videoData: JSON. Video configurations. See Alibaba Cloud's documentation for details about the following parameters:
        • title: String. The title of the video.
        • description: (Optional) String. The description of the video.
        • coverUrl: (Optional) String. The URL of the custom video thumbnail.
        • cateId: (Optional) String. The ID of the video category.
        • tags: (Optional) String. The tags of the video.
        • templateGroupId: (Optional) String. The ID of the transcoding template group.
        • userData: (Optional) String. The custom configurations.
        • storageLocation: (Optional) String. The bucket.
        • workflowId: (Optional) String. The ID of the workflow.

  Web page recording
  When using web page recording, extensionServices includes the following fields:

  • serviceName: String. The name of the extension service. To use web page recording, set it as "web_recorder_service".
  • errorHandlePolicy: (Optional) String. Error handling policy. Currently you can only set it to the default value, "error_abort", which means that if an error occurs to the current extension service, other extension services also stop.
  • serviceParam: JSON. Configurations for an extension service. To use web page recording, configure as follows:
    • url：String. Sets the address of the web page to record.
    • videoBitrate：(Optional) Number. Sets the bitrate of the video (Kbps). The value range is [50,8000]. The default value of videoBitrate varies according to the resolution of the output video:
      • 1280 × 720: The default value is 1130.
      • 960 × 720: The default value is 910.
      • 848 × 480: The default value is 610.
      • 640 × 480: The default value is 400.
      • For all other resolutions, the default value is 300.
    • videoFps: (Optional)Number. Sets the frame rate of the video (fps). The value range is [5,60]. The default value is 15.
    • audioProfile：Number. Sets the sample rate, encoding mode, number of audio channels, and bitrate.
      • 0: (Default) Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.
      • 1: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
      • 2: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.
    • videoWidth：Number. Sets the width of the video (pixels). The value range is [480,1280]. The product of videoWidth and videoHeight should not exceed 921,600 (1280 × 720).
    • videoHeight：Number. Sets the height of the video (pixels). The value range is [480,1280]. The product of videoWidth and videoHeight should not exceed 921,600 (1280 × 720).
    • maxRecordingHour：Number. Sets the maximum recording length (hours). If the limit is exceeded, the recording stops automatically. The value range is [1,720]. The default value is 3. We recommend that you set a value smaller than the value of resourceExpiredHour specified in the acquire method.

An HTTP request example of start

• The request URL is：

https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start

• Content-type is application/json;charset=utf-8.

• Authorization is basic HTTP authentication, see RESTful API authentication for details.

• The request body

  Audio and video recording in a channel

  {
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "recordingConfig": {
            "maxIdleTime": 30,
            "streamTypes": 2,
            "channelType": 0, 
            "transcodingConfig": {
                "height": 640, 
                "width": 360,
                "bitrate": 500, 
                "fps": 15, 
                "mixedVideoLayout": 1,
                "backgroundColor": "#FF0000"
                        },
            "subscribeVideoUids": ["123","456"], 
            "subscribeAudioUids": ["123","456"],
            "subscribeUidGroup": 0
        }, 
        "recordingFileConfig": {
            "avFileType": ["hls"]
        },
        "storageConfig": {
            "accessKey": "xxxxxxf",
            "region": 3,
            "bucket": "xxxxx",
            "secretKey": "xxxxx",
            "vendor": 2,
            "fileNamePrefix": ["directory1","directory2"]
        }
    }
  }

  VoD service

  {
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "recordingConfig": {
            "maxIdleTime": 30,
            "streamTypes": 2,
            "channelType": 0,
            "subscribeUidGroup": 0
       },
        "extensionServiceConfig": {
          "extensionServices": [{
            "serviceName": "aliyun_vod_service",
            "serviceParam": {
              "secretKey": "xxxxxx",
              "accessKey": "xxxxxx",
              "regionId": "cn-shanghai",
              "apiData": {
                "videoData": {
                  "title": "My Video",
                  "description": "This is my first video",
                  "coverUrl": "http://xxxxx"
               }
             }
           }
         }]
       }
   }
  }

  Capture snapshots

  {
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "recordingConfig": {
            "maxIdleTime": 30,
            "streamTypes": 2,
            "channelType": 0, 
            "subscribeUidGroup": 0
        }, 
        "snapshotConfig": {
            "captureInterval": 5,
            "fileType": ["jpg"]
        },
        "storageConfig": {
            "accessKey": "xxxxxxf",
            "region": 3,
            "bucket": "xxxxx",
            "secretKey": "xxxxx",
            "vendor": 2,
            "fileNamePrefix": ["directory1","directory2"]
        } 
    }
  }

  Web page recording

    {
    "cname":"httpClient463224",
    "uid":"527841",
    "clientRequest":{
        "token": "<token if any>",
        "extensionServiceConfig": {
             "errorHandlePolicy": "error_abort",
             "extensionServices":[{
                  "serviceName":"web_recorder_service",
                  "errorHandlePolicy": "error_abort",
                  "serviceParam": {
                      "url": "https://xxxxx",
                      "audioProfile":0,
                      "videoWidth":1280,
                      "videoHeight":720,
                      "maxRecordingHour":72
                 }
             }]
       },
        "recordingFileConfig":{
            "avFileType":[
                "hls",
                "mp4"
           ]
       },
        "storageConfig":{
            "vendor":2,
            "region":3,
            "bucket":"xxxxx",
            "accessKey":"xxxxx",
            "secretKey":"xxxxx",
            "fileNamePrefix":[
                "directory1",
                "directory2"
           ]
       }
   }
  }

  A response example of start

  "Code": 200,
  "Body":
  {
  "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a", 
  "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
  }

• code: Number. Status code.

• resourceId: String. The resource ID for cloud recording. The resource ID is valid for five minutes.

• sid: String. The recording ID. The unique identification of the current recording.

Update the subscription lists

During a cloud recording, you can call this method to update the subscription lists multiple times. This method call overrides the existing subscription configuration.

• Method: POST
• Endpoint: /v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/update

The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you want to raise the limit.

Parameters

The following parameters are required in the URL:

The following parameters are required in the request body:

streamSubscribe requires the following parameters:

• audioUidList: (Optional) JSON. The audio subscription list. If you set this parameter, do not set streamTypes in recordingConfig as 1 (video only).
  • subscribeAudioUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you want to subscribe. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.
  • unsubscribeAudioUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you do not want to subscribe. Once you set this parameter, the recording service subscribes to the audio of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.
• videoUidList: (Optional) JSON. The video subscription list. If you set this parameter, do not set streamTypes in recordingConfig as 0 (audio only).
  • subscribeVideoUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you want to subscribe. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.
  • unsubscribeVideoUids: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you do not want to subscribe. Once you set this parameter, the recording service subscribes to the video of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.

A request example of update

• The request URL is:

  https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/update

• Content-type is application/json;charset=utf-8.

• Authorization is the basic authorization. See RESTful API authentication for details.

• The request body:

  {
  "uid": "527841",
  "cname": "httpClient463224",
  "clientRequest": {
  "streamSubscribe": {
   "audioUidList": {
    "subscribeAudioUids": ["#allstream#"]
   },
   "videoUidList": {
    "unSubscribeVideoUids": ["444", "555", "666"]
   }
  }
  }
  }                                                         

A response example of update

"Code": 200,
"Body":
{
  "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a", 
  "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}

• code: Number. Status code.
• resourceId: String. The resource ID for cloud recording.
• sid: String. The recording ID. The unique identification of the current recording.

Updates the video mixing layout

During a recording, you can call this method to update the video mixing layout multiple times.

This method call overrides the existing layout configurations. For example, if you set the backgroundColor parameter as "#FF0000" (red) when starting a recording and call this method to update the layout without setting the backgroundColor parameter, the background color changes back to black (the default value).

• Method: POST
• Endpoint: /v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/updateLayout

The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you want to raise the limit.

Parameters

The following parameters are required in the URL.

The following parameters are required in the request body.

clientRequest requires the following parameters:

• maxResolutionUid: (Optional) String. When the layoutType parameter is set as 2 (vertical layout), you can specify the UID of the large video window by this parameter.
• mixedVideoLayout: (Optional) Number. The video mixing layout. 0, 1, and 2 are the predefined layouts. If you set this parameter as 3, you need to set the layout by the layoutConfig parameter.
  • 0: (Default) Floating layout. The first user in the channel occupies the full canvas. The other users occupy the small regions on top of the canvas, starting from the bottom left corner. The small regions are arranged in the order of the users joining the channel. This layout supports one full-size region and up to four rows of small regions on top with four regions per row, comprising 17 users.
  • 1: Best fit layout. This is a grid layout. The number of columns and rows and the grid size vary depending on the number of users in the channel. This layout supports up to 17 users.
  • 2: Vertical layout. One large region is displayed on the left edge of the canvas, and several smaller regions are displayed along the right edge of the canvas. The space on the right supports up to 2 columns of small regions with 8 regions per column. This layout supports up to 17 users.
  • 3: Customized layout. Set the layoutConfig parameter to customize the layout.
• backgroundColor: (Optional) String. The background color of the canvas (the display window or screen) in RGB hex value. The string starts with a "#". The default value is "#000000", the black color.
• layoutConfig: (Optional) JSONArray. An array of the configuration of each user's region. Supports 17 users at most. Each user's region configuration is a JSON object with the following parameters:
  • uid: (Optional) String. The string contains the UID of the user displaying the video in the region. If this parameter is not specified, the configurations apply in the order of the users joining the channel.
  • x_axis: (Mandatory) Float. The relative horizontal position of the top-left corner of the region. The value is between 0.0 (leftmost) and 1.0 (rightmost). x_axis can also be an integer 0 or 1.
  • y_axis: (Mandatory) Float. The relative vertical position of the top-left corner of the region. The value is between 0.0 (top) and 1.0 (bottom). y_axis can also be an integer 0 or 1.
  • width: (Mandatory) Float. The relative width of the region. The value is between 0.0 and 1.0. width can also be an integer 0 or 1.
  • height: (Mandatory) Float. The relative height of the region. The value is between 0.0 and 1.0. height can also be an integer 0 or 1.
  • alpha: (Optional) Float. The transparency of the image. The value is between 0.0 (transparent) and 1.0 (opaque). The default value is 1.0.
  • render_mode: (Optional) Number. The video display mode:
    • 0: (Default) Cropped mode. Uniformly scales the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.
    • 1: Fit mode. Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.

A request example of updateLayout

• The request URL is:

  https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/updateLayout

• Content-type is application/json;charset=utf-8.

• Authorization is the basic authorization, see RESTful API authentication for details.

• The request body:

  {
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "mixedVideoLayout": 3,
        "backgroundColor": "#FF0000",
        "layoutConfig": [
        {
             "uid": "1",
             "x_axis": 0.1,
             "y_axis": 0.1,
             "width": 0.1,
             "height": 0.1,
             "alpha": 1.0,
             "render_mode": 1
         },
        {
             "uid": "2",
             "x_axis": 0.2,
             "y_axis": 0.2,
             "width": 0.1,
             "height": 0.1,
             "alpha": 1.0,
             "render_mode": 1
         }
         ]
     }
  }

A response example of updateLayout

"Code": 200,
"Body":
{
  "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a", 
  "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}

• code: Number. Status code.
• resourceId: String. The resource ID for cloud recording. The resource ID is valid for five minutes.
• sid: String. The recording ID. The unique identification of the current recording.

Query the recording status

After you start a recording, you can call query to check its status.

• Method: GET
• Endpoint: /v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/query

The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you need to raise the limit.

Parameters

The following parameters are required in the URL.

An HTTP request example of query

• The request URL is:

  https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/query

• Content-type is application/json;charset=utf-8.
• Authorization is the basic authentication, see RESTful API authentication for details.

A response example of query

"Code": 200,
"Body":
{
  "resourceId":"JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
  "sid":"38f8e3cfdc474cd56fc1ceba380d7e1a",
  "serverResponse":{
    "fileListMode": "json",
    "fileList": [
   {
      "filename": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "123",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1562724971626
   },    
   {
      "filename": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "456",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1562724971626
   }
   ],
    "status": "5",
    "sliceStartTime": 1562724971626
   }       
}

• code: Number. Status code.

• resourceId: String. The resource ID for cloud recording. The resource ID is valid for five minutes.

• sid: String. The recording ID. The unique identification of the current recording.

• serverResponse: JSON. The details about the recording status.

  The child elements in serverResponse vary according to your configurations in start. For example, if you configure snapshotConfig or extensionServiceConfig in start, then query does not return fileListMode.

  • fileListMode: String. The data type of fileList.

    • "string": fileList is a string. In composite mode, fileListMode is "string".
    • "json": fileList is a JSONArray. In individual mode, fileListMode is "json".

  • fileList: When fileListMode is "string", fileList is a string that represents the filename of the M3U8 file. When fileListMode is "json", fileList is a JSONArray that contains the details of each recorded file. The query method does not return this field if you have set snapshotConfig.

    • filename: String. The name of the M3U8 file.
    • trackType: String. The type of the recorded file.
      • "audio": Audio file.
      • "video": Video file (no audio).
      • "audio_and_video": Video file (with audio).
    • uid: String. User ID. The user whose audio or video is recorded in the file.
    • mixedAllUser: Boolean. Whether the audio and video of all users are combined into a single file.
      • true: All users are recorded in a single file.
      • false: Each user is recorded separately.
    • isPlayable: Boolean. Whether the file can be played online.
      • true: The file can be played online.
      • false: The file cannot be played online.
    • sliceStartTime: Number. The Unix time (ms) when the recording starts.

  • status: Number. The status of the cloud service.

    • 0: The cloud service has not started.
    • 1: The initialization is complete.
    • 2: The cloud service is starting.
    • 3: The cloud service is partially ready.
    • 4: The cloud service is ready.
    • 5: The cloud service is in progress.
    • 6: The cloud service receives the request to stop.
    • 7: The cloud service stops.
    • 8: The cloud service exits.
    • 20: The cloud service exits abnormally.

  • sliceStartTime: Number. The time when the recording starts. Unix timestamp (ms).

  • extensionServiceState: JSONArray. An array of the detailed status information of each extension service.

    ApsaraVideo for VoD

    • serviceName: String. The name of the extension service. aliyun_vod_service means ApsaraVideo for VoD.
    • payload: JSON. The status of the extension service.
      • state: String. The status of uploading media content to the extension service.
        • "inProgress": The recorded files are being uploaded to the extension service.
        • "idle": No user is sending streams in the channel. Nothing is being uploaded.
      • videoInfo: JSONArray. An array of the M3U8 files and their corresponding video IDs. ApsaraVideo for VoD generates a video ID for each M3U8 file uploaded.
        • fileName: String. The name of the M3U8 file.
        • videoId: String. The corresponding video ID of the M3U8 file.

    Web page recording

    • serviceName: String . The name of the extension service. "web_recorder_service" means web page recording.
    • payload: JSON. The status of the extension service.
      • state: String. The status of uploading subscribed content to the extension service.
        • "init": The service is initializing.
        • "inProgress": The service has initialized and is working.
        • "exit": The service exits.
      • fileList: JSONArray. An array that contains details of each recorded file.
        • fileName: String. The name of the M3U8 file or MP4 file.
        • sliceStartTime: Number. The Unix timestamp (ms) when the recording starts.:

  • subServiceStatus: JSON. The status of the cloud recording submodules. The recording service does not return this field in web page recording mode.

    • recordingService: String. The status of the video subscription submodule. For details, see Service status.

Stop cloud recording

When a recording finishes, call stop to leave the channel and stop recording. To use Agora Cloud Recording again, you need to call the acquire method for a new resource ID.

• Method: POST
• Endpoint: /v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/stop

• The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you need to raise the limit.
• By default, Agora Cloud Recording automatically leaves the channel and stops recording if there are ever no users in the channel for more than 30 seconds.

Parameters

The following parameters are required in the URL.

The following parameters are required in the request body.

An HTTP request example of stop

• The request URL is:

  https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/stop

• Content-type is application/json;charset=utf-8.

• Authorization is the basic authentication, see RESTful API authentication for details.

• The request body:

  {
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest":{
    }
  }

A response example of stop

"Code": 200,
"Body":
{
  "resourceId":"JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
  "sid":"38f8e3cfdc474cd56fc1ceba380d7e1a",
  "serverResponse":{
    "fileListMode": "json",
    "fileList": [
    {
      "filename": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "123",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1562724971626
    },
    {
      "filename": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "456",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1562724971626
    }
    ],
    "uploadingStatus": "uploaded"
  }
}

• code: Number. Status code.

• resourceId: String. The resource ID for cloud recording. The resource ID is valid for five minutes.

• sid: String. The recording ID. The unique identification of the current recording.

• serverResponse: JSON. The details about the recording status. The child elements in serverResponse vary according to your configurations in start. For example, if you configure snapshotConfig or extensionServiceConfig in start, then stop does not return fileListMode.

  • fileListMode: String. The data type of fileList.

    • "string": fileList is a string. In composite mode, fileListMode is "string".
    • "json": fileList is a JSONArray. In individual mode, fileListMode is "json".

  • fileList: When fileListMode is "string", fileList is a string that represents the filename of the M3U8 file. When fileListMode is "json", fileList is a JSONArray that contains the details of each recorded file.

    • filename: String. The name of the M3U8 file.
    • trackType: String. The type of the recorded file.
      • "audio": Audio file.
      • "video": Video file (no audio).
      • "audio_and_video": Video file (with audio).
    • uid: String. User ID. The user whose audio or video is recorded in the file.
    • mixedAllUser: Boolean. Whether the audio and video of all users are combined into a single file.
      • true: All users are recorded in a single file.
      • false: Each user is recorded separately.
    • isPlayable: Boolean. Whether the file can be played online.
      • true: The file can be played online.
      • false: The file cannot be played online.
    • sliceStartTime: Number. The Unix time (ms) when the recording starts.

  • uploadingStatus: String. The upload status.

    • "uploaded": All the recorded files are uploaded to the third-party cloud storage.
    • "backuped": Some of the recorded files fail to upload to the third-party cloud storage and upload to Agora Cloud Backup instead. Agora Cloud Backup automatically uploads these files to your cloud storage.
    • "unknown": Unknown status.

  • extensionServiceState: JSONArray. An array of the detailed status information of each service.
    Uploading service

    • serviceName: String. The name of the service. "upload_service" means the uploading service.
    • payload: JSON. The status of the service.
      • uploadingStatus: String. The uploading status.
        • "uploaded": All the recorded files are uploaded to the third-party cloud storage.
        • "backuped": All the recorded files are uploaded, but at least one TS file is uploaded to Agora Cloud Backup. Agora Cloud Backup will automatically upload these files to your cloud storage later.
        • "unknown": Unknown status.

    Web page recording

    • serviceName: String. The name of the service. "web_recorder_service" means web page recording.
    • payload: JSON. The status of the extension service.
      • state: String. The status of uploading subscribed content to the extension service.
        • "init": The service is initializing.``
        • "inProgress": The service has initialized and is working.
        • "exit": The service exits.
      • fileList: JSONArray. An array that contains detailed information of each recorded file.
        • fileName: String. The name of the M3U8 file or MP4 file.
        • sliceStartTime: Number. The Unix timestamp (ms) when the recording starts.

Status code

Service status

Errors

This section lists the common errors you may encounter when using the Agora Cloud Recording RESTful APIs. If you encounter other errors, contact support@agora.io.

• 2: Invalid parameter. Possible reasons:

  • A parameter's data type is wrong.
  • A parameter is spelt wrong. All the parameters are case sensitive.
  • A parameter value is out of range.
  • A mandatory parameter is missing.

• 7: The recording is already running. Do not repeat the start request with the same resource ID.

• 8: Errors in the HTTP request header fields. Possible reasons:

  • Content-type is wrong. Ensure that the Content-type field is application/json;charset=utf-8.
  • cloud_recording is missing in the request URL.
  • The HTTP method is wrong.
  • The request is not valid JSON

• 49: Caused by repeated stop requests with the same resource ID and recording ID (sid).

• 53: The recording is already running. This error occurs when you use the same parameters to call acquire again and use the new resource ID in the start request. To start multiple recording instances, use a different UID for each instance.

• 62: If you receive this error when calling acquire, the cloud recording service is not enabled. See Enable Cloud Recording for details.

• 65: Usually caused by network jitter. Retry with the same resource ID. Agora recommends that you use a backoff strategy, for example, retry after 3 and 6 seconds successively.

• 432: The parameter in the request is incorrect. Either the parameter is invalid, or the App ID, channel name, or UID does not match the resource ID.

• 433: The resource ID has expired. You need to start recording within five minutes after getting a resource ID. Call acquire to get a new resource ID.

• 435: No recorded files created. There is nothing to record because no user is sending any stream in the channel.

• 501: The recording service is exiting. This error might occur when you call query after stop.

• 1001: Fails to parse the resource ID. Call acquire to get a new resource ID.

• 1003: The App ID or recording ID (sid) does not match the resource ID. Ensure that the App ID or recording ID matches the resource ID in each recording session.

• 1013: The channel name is invalid. The string length must be less than 64 bytes. Supported character scopes are:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

• 1028: Invalid parameters in the request body of the updateLayout method.

• "invalid appid": The App ID you entered is invalid. If the error persists after you verify the App ID, contact support@agora.io.

• "no Route matched with those values": A possible reason for this message is that you entered an incorrect HTTP method in your request, such as using GET when it should have been POST. Another possible reason is that you sent your request to a wrong URL.

• "Invalid authentication credentials": The following list contains possible reasons for this message. If the error persists after you correct the following issues, contact support@agora.io:

  • The Customer ID or Customer Certificate you entered is incorrect.
  • The cloud recording service is not enabled. See Enable Cloud Recording for details.
  • HTTP header contains incorrect information. For example, Basic is missing in the Authorization field.
  • HTTP header contains incorrectly formatted content. For example, the capitalization is wrong or there is an unnecessary space in the Content-type field. The correct value is application/json;charset=utf-8.