API Reference

Realtime Kit

Recordings

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Start recording a meeting

realtime_kit.recordings.start_recordings(strapp_id, RecordingStartRecordingsParams**kwargs) -> RecordingStartRecordingsResponse

POST/accounts/{account_id}/realtime/kit/{app_id}/recordings

Starts recording a meeting. The meeting can be started by an App admin directly, or a participant with permissions to start a recording, based on the type of authorization used.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Realtime AdminRealtime

ParametersExpand Collapse

account_id: str

The account identifier tag.

maxLength32

app_id: str

The app identifier tag.

meeting_id: str

ID of the meeting to record.

formatuuid

allow_multiple_recordings: Optional[bool]

By default, a meeting allows only one recording to run at a time. Enabling the allow_multiple_recordings parameter to true allows you to initiate multiple recordings concurrently in the same meeting. This allows you to record separate videos of the same meeting with different configurations, such as portrait mode or landscape mode.

audio_config: Optional[AudioConfig]

Object containing configuration regarding the audio that is being recorded.

channel: Optional[Literal["mono", "stereo"]]

Audio signal pathway within an audio file that carries a specific sound source.

One of the following:

"mono"

"stereo"

codec: Optional[Literal["MP3", "AAC"]]

Codec using which the recording will be encoded. If VP8/VP9 is selected for videoConfig, changing audioConfig is not allowed. In this case, the codec in the audioConfig is automatically set to vorbis.

One of the following:

"MP3"

"AAC"

export_file: Optional[bool]

Controls whether to export audio file seperately

file_name_prefix: Optional[str]

Update the recording file name.

interactive_config: Optional[InteractiveConfig]

Allows you to add timed metadata to your recordings, which are digital markers inserted into a video file to provide contextual information at specific points in the content range. The ID3 tags containing this information are available to clients on the playback timeline in HLS format. The output files are generated in a compressed .tar format.

type: Optional[Literal["ID3"]]

The metadata is presented in the form of ID3 tags.

max_seconds: Optional[int]

Specifies the maximum duration for recording in seconds, ranging from a minimum of 60 seconds to a maximum of 24 hours.

maximum86400

minimum60

realtimekit_bucket_config: Optional[RealtimekitBucketConfig]

enabled: bool

Controls whether recordings are uploaded to RealtimeKit’s bucket. If set to false, download_url, audio_download_url, download_url_expiry won’t be generated for a recording.

rtmp_out_config: Optional[RtmpOutConfig]

rtmp_url: Optional[str]

RTMP URL to stream to

formaturi

storage_config: Optional[StorageConfig]

One of the following:

class StorageConfigUnionMember0: …

access_key: Optional[str]

Access key of the storage medium. Access key is not required for the gcs storage media type.

Note that this field is not readable by clients, only writeable.

auth_method: Optional[Literal["KEY", "PASSWORD"]]

Authentication method used for “sftp” type storage medium

One of the following:

"KEY"

"PASSWORD"

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

password: Optional[str]

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

private_key: Optional[str]

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

region: Optional[str]

Region of the storage medium.

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["gcs"]]

username: Optional[str]

SSH destination server username for SFTP type storage medium

class StorageConfigUnionMember1: …

access_key: object

minLength1

region: object

minLength1

auth_method: Optional[Literal["KEY", "PASSWORD"]]

Authentication method used for “sftp” type storage medium

One of the following:

"KEY"

"PASSWORD"

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

password: Optional[str]

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

private_key: Optional[str]

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["aws", "azure", "digitalocean"]]

One of the following:

"aws"

"azure"

"digitalocean"

username: Optional[str]

SSH destination server username for SFTP type storage medium

class StorageConfigUnionMember2: …

private_key: str

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

access_key: Optional[str]

Access key of the storage medium. Access key is not required for the gcs storage media type.

Note that this field is not readable by clients, only writeable.

auth_method: Optional[Literal["KEY"]]

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

password: Optional[str]

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

region: Optional[str]

Region of the storage medium.

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["aws", "azure", "digitalocean", 2 more]]

Type of storage media.

One of the following:

"aws"

"azure"

"digitalocean"

"gcs"

"sftp"

username: Optional[str]

SSH destination server username for SFTP type storage medium

class StorageConfigUnionMember3: …

password: str

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

access_key: Optional[str]

Access key of the storage medium. Access key is not required for the gcs storage media type.

Note that this field is not readable by clients, only writeable.

auth_method: Optional[Literal["PASSWORD"]]

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

private_key: Optional[str]

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

region: Optional[str]

Region of the storage medium.

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["aws", "azure", "digitalocean", 2 more]]

Type of storage media.

One of the following:

"aws"

"azure"

"digitalocean"

"gcs"

"sftp"

username: Optional[str]

SSH destination server username for SFTP type storage medium

url: Optional[str]

Pass a custom url to record arbitary screen

formaturi

video_config: Optional[VideoConfig]

codec: Optional[Literal["H264", "VP8", "VP9"]]

Codec using which the recording will be encoded.

One of the following:

"H264"

"VP8"

"VP9"

export_file: Optional[bool]

Controls whether to export video file seperately

height: Optional[int]

Height of the recording video in pixels

maximum1920

minimum1

watermark: Optional[VideoConfigWatermark]

Watermark to be added to the recording

position: Optional[Literal["left top", "right top", "left bottom", "right bottom"]]

Position of the watermark

One of the following:

"left top"

"right top"

"left bottom"

"right bottom"

size: Optional[VideoConfigWatermarkSize]

Size of the watermark

height: Optional[int]

Height of the watermark in px

minimum1

width: Optional[int]

Width of the watermark in px

minimum1

url: Optional[str]

URL of the watermark image

formaturi

width: Optional[int]

Width of the recording video in pixels

maximum1920

minimum1

ReturnsExpand Collapse

class RecordingStartRecordingsResponse: …

success: bool

Success status of the operation

data: Optional[Data]

Data returned by the operation

id: str

ID of the recording

formatuuid

audio_download_url: Optional[str]

If the audio_config is passed, the URL for downloading the audio recording is returned.

formaturi

download_url: Optional[str]

URL where the recording can be downloaded.

formaturi

download_url_expiry: Optional[datetime]

Timestamp when the download URL expires.

formatdate-time

file_size: Optional[float]

File size of the recording, in bytes.

invoked_time: datetime

Timestamp when this recording was invoked.

formatdate-time

output_file_name: str

File name of the recording.

session_id: Optional[str]

ID of the meeting session this recording is for.

formatuuid

started_time: Optional[datetime]

Timestamp when this recording actually started after being invoked. Usually a few seconds after invoked_time.

formatdate-time

status: Literal["INVOKED", "RECORDING", "UPLOADING", 3 more]

Current status of the recording.

One of the following:

"INVOKED"

"RECORDING"

"UPLOADING"

"UPLOADED"

"ERRORED"

"PAUSED"

stopped_time: Optional[datetime]

Timestamp when this recording was stopped. Optional; is present only when the recording has actually been stopped.

formatdate-time

recording_duration: Optional[int]

Total recording time in seconds.

start_reason: Optional[DataStartReason]

caller: Optional[DataStartReasonCaller]

name: Optional[str]

Name of the user who started the recording.

type: Optional[Literal["ORGANIZATION", "USER"]]

The type can be an App or a user. If the type is user, then only the user_Id and name are returned.

One of the following:

"ORGANIZATION"

"USER"

user_id: Optional[str]

The user ID of the person who started the recording.

formatuuid

reason: Optional[Literal["API_CALL", "RECORD_ON_START"]]

Specifies if the recording was started using the “Start a Recording”API or using the parameter RECORD_ON_START in the “Create a meeting” API.

If the recording is initiated using the “RECORD_ON_START” parameter, the user details will not be populated.

One of the following:

"API_CALL"

"RECORD_ON_START"

stop_reason: Optional[DataStopReason]

caller: Optional[DataStopReasonCaller]

name: Optional[str]

Name of the user who stopped the recording.

type: Optional[Literal["ORGANIZATION", "USER"]]

The type can be an App or a user. If the type is user, then only the user_Id and name are returned.

One of the following:

"ORGANIZATION"

"USER"

user_id: Optional[str]

The user ID of the person who stopped the recording.

formatuuid

reason: Optional[Literal["API_CALL", "INTERNAL_ERROR", "ALL_PEERS_LEFT"]]

Specifies the reason why the recording stopped.

One of the following:

"API_CALL"

"INTERNAL_ERROR"

"ALL_PEERS_LEFT"

storage_config: Optional[DataStorageConfig]

One of the following:

class DataStorageConfigUnionMember0: …

access_key: Optional[str]

Access key of the storage medium. Access key is not required for the gcs storage media type.

Note that this field is not readable by clients, only writeable.

auth_method: Optional[Literal["KEY", "PASSWORD"]]

Authentication method used for “sftp” type storage medium

One of the following:

"KEY"

"PASSWORD"

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

password: Optional[str]

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

private_key: Optional[str]

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

region: Optional[str]

Region of the storage medium.

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["gcs"]]

username: Optional[str]

SSH destination server username for SFTP type storage medium

class DataStorageConfigUnionMember1: …

access_key: object

minLength1

region: object

minLength1

auth_method: Optional[Literal["KEY", "PASSWORD"]]

Authentication method used for “sftp” type storage medium

One of the following:

"KEY"

"PASSWORD"

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

password: Optional[str]

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

private_key: Optional[str]

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["aws", "azure", "digitalocean"]]

One of the following:

"aws"

"azure"

"digitalocean"

username: Optional[str]

SSH destination server username for SFTP type storage medium

class DataStorageConfigUnionMember2: …

private_key: str

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

access_key: Optional[str]

Access key of the storage medium. Access key is not required for the gcs storage media type.

Note that this field is not readable by clients, only writeable.

auth_method: Optional[Literal["KEY"]]

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

password: Optional[str]

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

region: Optional[str]

Region of the storage medium.

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["aws", "azure", "digitalocean", 2 more]]

Type of storage media.

One of the following:

"aws"

"azure"

"digitalocean"

"gcs"

"sftp"

username: Optional[str]

SSH destination server username for SFTP type storage medium

class DataStorageConfigUnionMember3: …

password: str

SSH destination server password for SFTP type storage medium when auth_method is “PASSWORD”. If auth_method is “KEY”, this specifies the password for the ssh private key.

access_key: Optional[str]

Access key of the storage medium. Access key is not required for the gcs storage media type.

Note that this field is not readable by clients, only writeable.

auth_method: Optional[Literal["PASSWORD"]]

bucket: Optional[str]

Name of the storage medium’s bucket.

host: Optional[str]

SSH destination server host for SFTP type storage medium

path: Optional[str]

Path relative to the bucket root at which the recording will be placed.

port: Optional[float]

SSH destination server port for SFTP type storage medium

private_key: Optional[str]

Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is “KEY”

region: Optional[str]

Region of the storage medium.

secret: Optional[str]

Secret key of the storage medium. Similar to access_key, it is only writeable by clients, not readable.

type: Optional[Literal["aws", "azure", "digitalocean", 2 more]]

Type of storage media.

One of the following:

"aws"

"azure"

"digitalocean"

"gcs"

"sftp"

username: Optional[str]

SSH destination server username for SFTP type storage medium

Start recording a meeting

Python

HTTP

TypeScript

Python

Go

Terraform

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.realtime_kit.recordings.start_recordings(
    app_id="14a396e7-ca44-4937-bf1f-050a69118543",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    meeting_id="97440c6a-140b-40a9-9499-b23fd7a3868a",
    allow_multiple_recordings=False,
    audio_config={
        "channel": "stereo",
        "codec": "AAC",
        "export_file": True,
    },
    file_name_prefix="string",
    interactive_config={
        "type": "ID3"
    },
    max_seconds=60,
    realtimekit_bucket_config={
        "enabled": True
    },
    video_config={
        "codec": "H264",
        "export_file": True,
        "height": 720,
        "watermark": {
            "position": "left top",
            "size": {
                "height": 1,
                "width": 1,
            },
            "url": "http://example.com",
        },
        "width": 1280,
    },
)
print(response.success)

200 example

{
  "success": true,
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "audio_download_url": "https://example.com",
    "download_url": "https://example.com",
    "download_url_expiry": "2019-12-27T18:11:19.117Z",
    "file_size": 0,
    "invoked_time": "2019-12-27T18:11:19.117Z",
    "output_file_name": "output_file_name",
    "session_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "started_time": "2019-12-27T18:11:19.117Z",
    "status": "INVOKED",
    "stopped_time": "2019-12-27T18:11:19.117Z",
    "recording_duration": 0,
    "start_reason": {
      "caller": {
        "name": "RealtimeKit_test",
        "type": "ORGANIZATION",
        "user_Id": "d61f6956-e68f-4375-bf10-c38a704d1bec"
      },
      "reason": "API_CALL"
    },
    "stop_reason": {
      "caller": {
        "name": "RealtimeKit_test",
        "type": "ORGANIZATION",
        "user_Id": "d61f6956-e68f-4375-bf10-c38a704d1bec"
      },
      "reason": "API_CALL"
    },
    "storage_config": {
      "auth_method": "KEY",
      "bucket": "bucket",
      "host": "host",
      "path": "path",
      "port": 0,
      "region": "us-east-1",
      "type": "gcs",
      "username": "username"
    }
  }
}

Returns Examples

200 example

{
  "success": true,
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "audio_download_url": "https://example.com",
    "download_url": "https://example.com",
    "download_url_expiry": "2019-12-27T18:11:19.117Z",
    "file_size": 0,
    "invoked_time": "2019-12-27T18:11:19.117Z",
    "output_file_name": "output_file_name",
    "session_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "started_time": "2019-12-27T18:11:19.117Z",
    "status": "INVOKED",
    "stopped_time": "2019-12-27T18:11:19.117Z",
    "recording_duration": 0,
    "start_reason": {
      "caller": {
        "name": "RealtimeKit_test",
        "type": "ORGANIZATION",
        "user_Id": "d61f6956-e68f-4375-bf10-c38a704d1bec"
      },
      "reason": "API_CALL"
    },
    "stop_reason": {
      "caller": {
        "name": "RealtimeKit_test",
        "type": "ORGANIZATION",
        "user_Id": "d61f6956-e68f-4375-bf10-c38a704d1bec"
      },
      "reason": "API_CALL"
    },
    "storage_config": {
      "auth_method": "KEY",
      "bucket": "bucket",
      "host": "host",
      "path": "path",
      "port": 0,
      "region": "us-east-1",
      "type": "gcs",
      "username": "username"
    }
  }
}