# Stop a cloud recording task (/en/api-reference/api-ref/cloud-recording/stop)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Stops an active cloud recording task.

- OpenAPI: /openapi/cloud-recording/cloud-recording.en.yaml
- Operation ID: stop-cloud-recording
- Method: POST
- Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop
- Endpoint: https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop

## Servers

- https://api.sd-rtn.com

Call this endpoint to leave the channel and stop cloud recording. To start recording again after stopping, call [`acquire`](acquire) to get a new resource ID.


:::info[Note]
- This endpoint is only valid within an active recording session. If the recording was not started successfully or has already ended, the request returns `404`.
- In non-web page recording modes, if the channel is idle for longer than the `maxIdleTime` value set in [`start`](start) (default 30 seconds), cloud recording automatically leaves the channel and stops.
:::

## Authorization

This endpoint requires authentication.

- `basicAuth`

## Parameters

- `Content-Type` (header, optional, string) - `application/json`.
  - Default: `application/json`
- `appid` (path, required, string) - The App ID of your project.
- For web page recording mode, enter the App ID for which the cloud recording service is enabled.
- For individual and composite recording modes, use the same App ID as the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
- `resourceid` (path, required, string) - The resource ID obtained from the `acquire` endpoint.
- `sid` (path, required, string) - The recording ID obtained from the `start` endpoint.
- `mode` (path, required, string) - The recording mode:
- `individual`: Individual recording mode.
- `mix`: Composite recording mode.
- `web`: Web page recording mode.
  - Allowed: `individual` | `mix` | `web`

## Request body

- `cname` (string, required) - The name of the channel to record. Must match the `cname` used in the `acquire` request.
The name of the channel being recorded.
- `uid` (string, required) - The UID used by the cloud recording service in the channel. Must match the `uid` used in the `acquire` request.
The UID used by the cloud recording service in the RTC channel.
- `clientRequest` (object, required)
  - `clientRequest.async_stop` (boolean) - The response mechanism for the `stop` request:
- `true`: Asynchronous. Returns a response immediately after the request is received, without waiting for the recording files to finish uploading.
- `false`: Synchronous. Returns a response only after all recorded files have been uploaded to third-party cloud storage. Agora expects the upload to complete within 20 seconds. If it exceeds this limit, the response returns error code `50`.
    - Default: `false`

### Request body example

```json
{
  "cname": "httpClient463224",
  "uid": "527841",
  "clientRequest": {
    "async_stop": false
  }
}
```

## Request examples

### curl

```bash
curl --request POST \
    --url https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop \
    --header 'Authorization: Basic <credentials>' \
    --header 'Content-Type: application/json' \
    --data '{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
      "async_stop": false
    }
  }'
```

### Python

```python
import requests
  import json

  url = "https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop"
  headers = {
      "Authorization": "Basic <credentials>",
      "Content-Type": "application/json"
  }

  data = {
      "cname": "httpClient463224",
      "uid": "527841",
      "clientRequest": {
          "async_stop": False
      }
  }

  response = requests.post(url, headers=headers, data=json.dumps(data))

  print(response.status_code)
  print(response.json())
```

### Node.js

```javascript
const axios = require('axios');

  const url = 'https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop';
  const headers = {
    'Authorization': 'Basic <credentials>',
    'Content-Type': 'application/json'
  };

  const data = {
    cname: "httpClient463224",
    uid: "527841",
    clientRequest: {
      async_stop: false
    }
  };

  axios.post(url, data, { headers })
    .then(response => {
      console.log('Status:', response.status);
      console.log('Data:', response.data);
    })
    .catch(error => {
      console.error('Error:', error.response ? error.response.data : error.message);
    });
```


### Response

- If the returned status code is `200`, the request was successful.

- If the returned status code is not `200`, the request failed. See [Response status codes](/en/api-reference/api-ref/cloud-recording/status-codes) for troubleshooting.


## Responses

### 200

The request succeeded.

- `serverResponse` (object) - The recording stop status. The fields returned vary depending on the recording mode and whether screenshot capture is enabled.
  - `serverResponse.extensionServiceState` (array) - State of each extension service at the time of stopping. Only returned in web page recording mode.
    - `serverResponse.extensionServiceState.items` (object)
      - `serverResponse.extensionServiceState.items.payload` (object) - Service-specific state at the time of stopping.
        - `serverResponse.extensionServiceState.items.payload.uploadingStatus` (string) - Upload status of the recording files. Only returned by `upload_service`.
- `"uploaded"`: All recording files have been uploaded to the specified third-party cloud storage.
- `"backuped"`: All files have been uploaded, but at least one TS file was uploaded to Agora backup cloud. The Agora server will automatically continue uploading to the designated third-party cloud storage.
- `"unknown"`: Unknown status.
        - `serverResponse.extensionServiceState.items.payload.fileList` (array) - Files generated during recording. Only returned by `web_recorder_service`.
          - `serverResponse.extensionServiceState.items.payload.fileList.items` (object)
            - `serverResponse.extensionServiceState.items.payload.fileList.items.filename` (string) - Name of the M3U8 or MP4 file.
            - `serverResponse.extensionServiceState.items.payload.fileList.items.sliceStartTime` (integer) - Recording start time of the file, Unix timestamp in seconds.
        - `serverResponse.extensionServiceState.items.payload.onhold` (boolean) - Whether recording was paused at the time of stopping. `true` if paused, `false` if running. Only returned by `web_recorder_service`.
        - `serverResponse.extensionServiceState.items.payload.state` (string) - Upload status of the extension service. Only returned by `web_recorder_service`.
- `"init"`: Initializing.
- `"inProgress"`: Running.
- `"exit"`: Stopped.
      - `serverResponse.extensionServiceState.items.serviceName` (string) - Extension service name:
- `"upload_service"`: Upload service.
- `"web_recorder_service"`: Web page recording service.
  - `serverResponse.uploadingStatus` (string) - Upload status of the recording files. Only returned in individual recording mode when screenshot capture is enabled, and in individual and composite recording modes when screenshot capture is not enabled.
- `"uploaded"`: All recording files have been uploaded to the specified third-party cloud storage.
- `"backuped"`: All files have been uploaded, but at least one TS file was uploaded to Agora backup cloud. The Agora server will automatically continue uploading to the designated third-party cloud storage.
- `"unknown"`: Unknown status.
  - `serverResponse.fileListMode` (string) - Data format of `fileList`. Only returned in individual and composite recording modes when screenshot capture is not enabled.
- `"string"`: In composite recording mode when `avFileType` is `["hls"]`.
- `"json"`: When `avFileType` is `["hls","mp4"]` in individual or composite recording mode.
  - `serverResponse.fileList` (string) - The recorded files. Only returned in individual and composite recording modes when screenshot capture is not enabled. When `fileListMode` is `"string"`, this is the filename of the M3U8 file. When `fileListMode` is `"json"`, this is an array of objects with the following fields:
    - `serverResponse.fileList.items` (object)
      - `serverResponse.fileList.items.fileName` (string) - Name of the M3U8 or MP4 file.
      - `serverResponse.fileList.items.trackType` (string) - File type:
- `"audio"`: Audio only.
- `"video"`: Video only.
- `"audio_and_video"`: Audio and video.
      - `serverResponse.fileList.items.uid` (string) - The UID whose stream is recorded. In composite recording mode, this is `"0"`.
      - `serverResponse.fileList.items.mixedAllUser` (boolean) - `true` if all users are recorded in a single file; `false` if each user is recorded separately.
      - `serverResponse.fileList.items.isPlayable` (boolean) - `true` if the file can be played online; `false` if it cannot.
      - `serverResponse.fileList.items.sliceStartTime` (integer) - Recording start time of the file, Unix timestamp in seconds.
- `resourceId` (string) - The cloud recording resource ID. Valid for five minutes; re-request from `acquire` if expired.

The resource ID used by cloud recording.
- `sid` (string) - The recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.

The recording ID, identifying the current recording session.
- `cname` (string) - The name of the channel to be recorded.

The name of the channel being recorded.
- `uid` (string) - The UID used by the cloud recording service in the RTC channel.
### default

The request failed. If the HTTP status code is not `200`, see the Cloud Recording response status codes for troubleshooting.

No schema.

## Response examples

### 200

```json
{
  "resourceId": "string",
  "sid": "string",
  "serverResponse": {
    "extensionServiceState": [
      {
        "payload": {
          "uploadingStatus": "string"
        },
        "serviceName": "string"
      }
    ]
  },
  "cname": "string",
  "uid": "string"
}
```

### Response example

```json
{
    "resourceId": "JyvK8nXHuV1BE.....",
    "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
    "serverResponse": {
      "extensionServiceState": [
        {
          "payload": {
            "uploadingStatus": "uploaded"
          },
          "serviceName": "upload_service"
        }
      ]
    },
    "cname": "httpClient463224",
    "uid": "527841"
  }
```

```json
{
    "code": 62,
    "reason": "request timeout"
   }
```