Documentation | Recordings › List Recordings

API Reference

Recordings

recordings

Methods

List Recordings -> OffsetPage<

Recording

get/recordings

List recordings

query Parameters

device: {

Optional

id: string

Optional

Equivalent to deviceId, and ignored if deviceId is supplied

name: string

Optional

Equivalent to deviceName, and ignored if deviceName is supplied

}

deviceId: string

Optional

Filter response to recordings for the device with this ID, empty string for those without any

deviceName: string

Optional

Filter response to recordings for the device with this name

edgeSite: {

Optional

id: string

Optional

Filter response to recordings stored at the Edge Site with this ID

}

end: string

Optional

(format: date-time)

End of inclusive time range: return all recordings with data on or before this value

importStatus:

Optional

Filter response to recordings with this import status

"none"

"pending"

"importing"

"failed"

"complete"

limit: number

Optional

(minimum: 0, maximum: 2000, default: 2000)

Maximum number of items to return

offset: number

Optional

(minimum: 0)

Number of items to skip before returning the results

path: string

Optional

Filter response to recordings with this path

site: {

Optional

id: string

Optional

Filter response to recordings stored at the Primary Site with this ID

}

sortBy:

Optional

Sort returned recordings by a field in the response type. Specifying duration sorts by the duration between the recording start and end fields.

"deviceName"

"device.name"

"createdAt"

"start"

"end"

"duration"

"path"

"importedAt"

sortOrder:

Optional

Sort order for the sortBy field

"asc"

"desc"

start: string

Optional

(format: date-time)

Start of inclusive time range: return all recordings with data on or after this value

topic: string

Optional

Filter response to recordings containing the topic

Response fields

id: string

ID of the recording

createdAt: string

(format: date-time)

Timestamp when the recording file was added to Foxglove.

end: string

(format: date)

The log time of the last message in the recording.

importStatus:

RecordingImportStatus

The import status of recordings. Status will be one of:

none: The recording has not yet been imported, and import has not been requested.
pending: Foxglove has received a request to import this recording.
importing: The recording data is being processed for access via Foxglove.
failed: The recording data could not be imported.
complete: The contents of the recording are available for access via Foxglove.

Note: none and pending statuses are applicable only to recordings originating from an Edge Site or Foxglove Agent.

The set of importStatus values may expand in the future.

path: string

The filepath of the recording as it was originally provided to Foxglove. For recordings originated at the edge, this is the full path of the recording file in the edge controller store. For recordings uploaded directly to Foxglove, this is the filename query arg provided to /data/upload.

size: number

(format: bigint)

The size of the recording file, in bytes

start: string

(format: date)

The log time of the first message in the recording.

device:

DeviceSummary

Optional

ID and name of a device.

edgeSite:

SiteSummary

Optional

The edge site for this recording.

importedAt: string

Optional

(format: date-time)

Timestamp when the recording was imported to a primary site.

key: string

Optional

The unique, user-specified key assigned to a recording in MCAP metadata or during the upload process. This can be used to identify the recording, in addition to its id.

metadata: Array<{ metadata, name }>

Optional

The metadata records of the original MCAP file content

site:

SiteSummary

Optional

The primary site for this recording.

Request example

curl https://api.foxglove.dev/v1/recordings \
    -H "Authorization: Bearer $FOXGLOVE_API_KEY"

200Example

[
  {
    "id": "id",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "end": "2019-12-27",
    "importStatus": "none",
    "path": "path",
    "size": 0,
    "start": "2019-12-27",
    "device": {
      "id": "id",
      "name": "name"
    },
    "edgeSite": {
      "id": "id",
      "name": "name"
    },
    "importedAt": "2019-12-27T18:11:19.117Z",
    "key": "key",
    "metadata": [
      {
        "metadata": {
          "foo": "string"
        },
        "name": "name"
      }
    ],
    "site": {
      "id": "id",
      "name": "name"
    }
  }
]

Get A Recording ->

Recording

get/recordings/{keyOrId}

Get details on a specific recording.

Delete A Recording -> { recordingId }

delete/recordings/{keyOrId}

Deletes a recording. Deleting a recording also deletes the data for that recording (including attachments, messages, metadata, etc).

Note: For recordings stored at an Edge Site, this method deletes only the imported data for that recording, leaving the edge copy intact.

Import From Edge -> { id, importStatus }

post/recordings/{keyOrId}/import

Request import of a recording from an Edge Site to a Primary Site. Importing a recording makes the data (messages, metadata, attachments, etc.) available for download and streaming.

If the recording is successfully queued for import, is already imported, or already queued for import, this endpoint will return a 200 response and include the recording ID and the importStatus.

An import status of complete indicates the recording is already imported. Poll the GET v1/recordings/{id} endpoint to observe changes to the importStatus.

If the recording cannot be found or is unavailable for import because the edge copy or site is deleted, this endpoint will return a 404 response.

Domain types

DeviceSummary = { id, name }

ID and name of a device.

Recording = { id, createdAt, end, 10 more... }

A resource representing the content of an MCAP file or ROS bag managed by Foxglove.

RecordingImportStatus = "none" | "pending" | "importing" | 2 more...

The import status of recordings. Status will be one of:

none: The recording has not yet been imported, and import has not been requested.
pending: Foxglove has received a request to import this recording.
importing: The recording data is being processed for access via Foxglove.
failed: The recording data could not be imported.
complete: The contents of the recording are available for access via Foxglove.

Note: none and pending statuses are applicable only to recordings originating from an Edge Site or Foxglove Agent.

The set of importStatus values may expand in the future.

SiteSummary = { id, name }

ID and name of a site.

Recordings

Recording Attachments

recordings.recording_attachments

Methods

List Attachments -> OffsetPage<

RecordingAttachment

get/recording-attachments

List attachments

Get An Attachment ->

RecordingAttachment

get/recording-attachments/{id}

Get an attachment

Download An Attachment ->

get/recording-attachments/{id}/download

To download an attachment make a request to this endpoint and follow the 302 redirect. The attachment will download directly from the Primary Site.

Note: The redirect link expires after 15 minutes.

Domain types

RecordingAttachment = { id, crc, createTime, 8 more... }

An attachment resource represents information about an MCAP attachment imported to Foxglove.