Chapter 11 GET POST

getRecordings – Retrieve Recordings

The getRecordings endpoint returns a list of recordings from your BigBlueButton server, filtered by meeting ID, recording ID, or state. It supports pagination starting with BBB 2.7, making it easy to retrieve large sets of recordings in manageable chunks.

Endpoint

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getRecordings?<parameters>&checksum=replace-with-checksum

Parameters

Parameter Type Required Default Description
meetingID String — — Comma-separated list of meeting IDs. Ignored when recordID is provided. If omitted, all recordings are returned.
recordID String — — Comma-separated list of recording IDs. Takes precedence over meetingID. Supports prefix matching — for example, 652c9eb4 matches all recordings whose ID starts with that prefix.
state String — published,unpublished Comma-separated state filter. Valid values: processing, processed, published, unpublished, deleted. Use any to return all states.
meta String — — Metadata filter using the same format as in the create call (e.g. meta_presenter=John).
offset Integer — 0 Start index for pagination. Only takes effect when limit is also provided. BBB 2.7+
limit Integer — — Maximum number of recordings per response (1 to 100). Values outside this range are clamped automatically. BBB 2.7+

None of the parameters are required. Calling getRecordings without any filter returns all published and unpublished recordings on the server.

Recording States

State Description
processing The recording is currently being processed.
processed Processing is complete, but the recording has not been published yet.
published The recording is published and accessible to users.
unpublished The recording exists but is not accessible to users.
deleted The recording has been marked for deletion.

The default state filter only includes published and unpublished recordings. To see recordings that are still being processed or have been deleted, you must explicitly set the state parameter.

Response Fields

Field Type Description
recordID String Unique identifier of the recording.
meetingID String The external meeting ID associated with this recording.
internalMeetingID String The internal meeting ID used by BigBlueButton.
name String The name of the meeting at the time it was recorded.
isBreakout Boolean Whether this recording is from a breakout room.
published Boolean Whether the recording is currently published.
state String Current state of the recording (processing, processed, published, unpublished, deleted).
startTime Long Unix timestamp in milliseconds when the meeting started.
endTime Long Unix timestamp in milliseconds when the meeting ended.
participants Integer Number of participants in the meeting.
rawSize Long Size of the raw recording data in bytes.
size Long Size of the processed recording in bytes.
metadata Object Custom metadata key-value pairs associated with the recording.
playback Object Playback format details including URL, processing time, length, size, and preview thumbnails.
totalElements Integer Total number of matching recordings. Only present when pagination parameters are used. BBB 2.7+

Example Request

All published recordings

getRecordings?checksum=replace-with-checksum

Recordings for a specific meeting

getRecordings?meetingID=replace-with-meeting-id&checksum=replace-with-checksum

Multiple meetings

getRecordings?meetingID=replace-with-meeting-id-1,replace-with-meeting-id-2&checksum=replace-with-checksum

By recording ID

getRecordings?recordID=replace-with-recording-id&checksum=replace-with-checksum

All states

getRecordings?state=any&checksum=replace-with-checksum

Paginated request (recordings 21 to 30)

getRecordings?state=published&offset=20&limit=10&checksum=replace-with-checksum

Example Response

<response>
  <returncode>SUCCESS</returncode>
  <recordings>
    <recording>
    <recordID>replace-with-recording-id</recordID>
    <meetingID>replace-with-meeting-id</meetingID>
    <internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
      <name>Project Meeting</name>
      <isBreakout>false</isBreakout>
      <published>true</published>
      <state>published</state>
      <startTime>1462283509434</startTime>
      <endTime>1462284509434</endTime>
      <participants>5</participants>
      <metadata>
        <bbb-origin>greenlight</bbb-origin>
      </metadata>
      <rawSize>123456789</rawSize>
      <size>98765432</size>
      <playback>
        <format>
          <type>presentation</type>
                    <url>https://api-guide.bbbserver.com/playback/presentation/2.3/replace-with-recording-id</url>
          <processingTime>62890</processingTime>
          <length>45</length>
          <size>98765432</size>
          <preview>
            <images>
              <image width="176" height="136" alt="Welcome">
                                https://api-guide.bbbserver.com/presentation/replace-with-recording-id/thumbnail_0.png
              </image>
            </images>
          </preview>
        </format>
      </playback>
    </recording>
  </recordings>
</response>

Pagination BBB 2.7+

When you include the offset and/or limit parameters, the response contains an additional totalElements field indicating the total number of matching recordings. This lets you calculate the total number of pages and build pagination controls in your application. 

<response>
  <returncode>SUCCESS</returncode>
  <totalElements>42</totalElements>
  <recordings>
    <!-- recording elements -->
  </recordings>
</response>
bbbserver.de — On bbbserver.de, the getRecordings endpoint is fully available through the API. Pagination is supported on all current server plans running BBB 2.7 or later.

Tips

  • Use recordID with a prefix to search for recordings when you only have a partial ID — BigBlueButton matches all recordings whose ID starts with the given string.
  • Always specify the state parameter explicitly if you need to see recordings that are still processing or have been deleted, as these are excluded by default.
  • Combine meetingID with state to narrow down results efficiently — for example, to find only published recordings for a specific meeting.
  • For large deployments with many recordings, use pagination to avoid timeouts and reduce response sizes.
  • Use metadata filters (meta_ parameters) to find recordings based on custom attributes set during meeting creation.

Frequently Asked Questions

The endpoint returns all recordings with a state of published or unpublished. Recordings that are still processing or have been marked for deletion are not included unless you explicitly set the state parameter.

When you provide a partial recording ID, BigBlueButton matches all recordings whose full ID starts with the given string. For example, passing 652c9eb4 will return every recording whose ID begins with that prefix. This is sometimes referred to as wildcard matching in the official documentation, but it is strictly prefix-based (startsWith), not substring matching.

Yes. Use the meta parameter with the same key names you set during meeting creation. For example, if you passed meta_presenter=John when creating the meeting, you can filter by the same key-value pair in getRecordings. Note that the exact matching behavior for metadata filters is not fully specified in the official documentation.

The meetingID is the external identifier you assigned when creating the meeting. A single meeting can produce multiple recordings. The recordID is a unique identifier for each individual recording. When both are provided, recordID takes precedence and meetingID is ignored.

Pagination requires BBB 2.7 or later. Set the limit parameter to control how many recordings are returned per request (1 to 100), and use offset to skip a number of results. The response will include a totalElements field so you can calculate the total number of pages. The offset parameter has no effect unless limit is also specified.

BigBlueButton automatically clamps the value to the allowed range. If you pass a value greater than 100, it is treated as 100. If you pass a value less than 1, it is treated as 1. No error is returned.

Yes. Breakout room recordings are included and can be identified by the isBreakout field set to true. They may also contain additional fields such as the parent meeting ID and the breakout sequence number.