Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

Clarification on Agora Cloud Recording File Delivery, S3 Configuration, and Instant Upload Behavior

Updated

Issue Description:

When calling the Agora Cloud Recording start and stop APIs for a one-to-one audio call, multiple output files (such as .m3u8 and .mp4) are generated, whereas only the final .mp3 call recording file is desired. In some cases, users also experience delays or missing files when recordings are uploaded to AWS S3 storage.

 

Platform/SDK:

Agora Cloud Recording RESTful API (used with AWS S3 Cloud Storage Integration)

 

Error Message (if applicable):

Error code 301: Unable to parse ExceptionName: PermanentRedirect Message: The bucket you are attempting to access must be addressed using the specified endpoint.

 

Step by Step Solution:

1. Verify Recording Mode and Target File Type

- When starting a recording session using the /cloud_recording/resourceid/{resourceId}/mode/mix/start API, specify only the desired output file format.

- In the recordingFileConfig section of your API request, include:

{
  "recordingFileConfig": {
    "avFileType": ["hls", "mp4"]
  }
}

Note: Agora Cloud Recording does not directly produce .mp3 files. Audio-only outputs are wrapped into .mp4 or .m3u8 files by default.

 

2. Ensure Correct AWS S3 Region Configuration

- The most common reason for missing or delayed uploads is a mismatch between the configured S3 region in the Agora request and the actual region of your S3 bucket.

- Update the region value in storageConfig to match your S3 bucket’s region code. Reference region codes from Agora’s documentation: Agora Region and Vendor Reference

{
  "storageConfig": {
    "vendor": 1,
    "region": 14, // correct region code for ap-south-1
    "bucket": "your-bucket-name",
    "accessKey": "your-access-key",
    "secretKey": "your-secret-key",
    "fileNamePrefix": ["recordings", "channelName"]
  }
}

 

3. Confirm IAM Permissions and S3 Access Policies

- The S3 bucket must allow programmatic upload using the provided accessKey and secretKey.

- Verify the IAM user or role has s3:PutObject, s3:ListBucket, and s3:GetObject permissions for the target path or prefix.

 

4. Check Instant File Availability Settings

- The recorded files are uploaded automatically after the stop recording API call completes. The typical upload latency is less than 20 seconds but may vary depending on file size or network latency.

- For faster (“instant”) upload behavior, keep the stop request synchronous by setting:

{
  "clientRequest": {
    "async_stop": false
  }
}

 

5. Handle Error Code 301

- If you encounter error code 301, it indicates that the S3 endpoint is not aligned with the specified region.

- This may cause delayed or failed uploads. Correct the region parameter using the official Agora region mapping.

 

6. Verify Upload Status

- Confirm upload status within the stop API response under serverResponse.uploadingStatus.

  • uploaded: File uploaded successfully.
  • backuped: File uploaded to a secondary location or in progress.

- If delays persist, ensure the region values and bucket endpoint match exactly and test with a smaller recording for verification.

 

Root Cause:

Incorrect region configuration or mismatch between the AWS S3 bucket endpoint and the region parameter in Agora’s storageConfig causes permanent redirect errors (301), leading to failed or delayed uploads of recorded files.

 

Prevention/Best Practice:

  • Always verify that the S3 region in your storageConfig matches the exact AWS bucket region and endpoint.
  • Use async_stop: false for more immediate file uploads.
  • Regularly review Agora best practices for Cloud Recording integrations: Agora Cloud Recording Best Practices

 

Corresponding Document/Link:

 

Related to

Related articles