Skip to main content
Loading...

API docs by

List recordings

Request

Security
ApiKey(Required scopes: recordings.list)
Query
startstring, (date-time)

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

endstring, (date-time)

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

pathstring

Filter response to recordings with this path

site.idstring

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

edgeSite.idstring

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

deviceIdstring

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

deviceNamestring

Filter response to recordings for the device with this name

topicstring

Filter response to recordings containing the topic

device.idstringdeprecated

Equivalent to deviceId, and ignored if deviceId is supplied

device.namestringdeprecated

Equivalent to deviceName, and ignored if deviceName is supplied

importStatusstring

Filter response to recordings with this import status

Enum:"none""pending""importing""failed""complete"
projectIdstring

Filter recordings by project

sessionIdstring

Filter response to recordings in the session with this ID, or empty string for recordings with no associated session

sessionKeystring

Filter response to recordings in the session with this key (sessions group recordings from a specific device)

metadataQuerystring

Filter recordings by metadata using a query syntax.

Supports key-value search variations (see Recordings Search):

  • key:value: matches recordings with metadata that contains a key named key with a value of value
  • key:value1,value2: matches recordings with metadata that contains a key named key with a value of either value1 or value2
  • key:*: matches recordings where any metadata contains a key named key
  • *:value: matches recordings where any metadata contains value as a value
  • search term: matches recordings with metadata where any key or value string contains search term

Multiple qualifiers can be used in the same query string; this will filter recordings where metadata matches the intersection of the qualifiers (AND).

Examples:

  • temperature:high - find recordings with sensor metadata where temperature is high
  • status:* device:camera1 - find recordings with any status AND device camera1
  • *:error - find any key with "error" value
  • warehouseName:"leaping llama" - use quotes for values with spaces or special characters

As this is a query parameter, the value must be URL-encoded.

limitnumber, [ 0 .. 2000 ]

Maximum number of items to return

Default:2000
offsetinteger, >= 0

Number of items to skip before returning the results

Default:0
sortBystring

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

Enum:"deviceName""device.name""createdAt""start""end""duration""path""importedAt"
sortOrderstring

Sort order for the sortBy field

Enum:"asc""desc"
Python
from foxglove.client import Client

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_recordings()

Responses

Success

Bodyapplication/json
Array [
idstringrequired

ID of the recording

projectIdstringrequired

The project ID that the recording belongs to

pathstringrequired

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.

locationobject(RecordingObjectLocation)

The object-store location of a recording. Present only when the recording is indexed in a customer-managed bucket. Omitted for query-optimized sites, where the original object is not retained, and for recordings that have not yet been imported.

sizenumber, (bigint)required

The size of the recording file, in bytes

createdAtstring, (date-time)required

Timestamp when the recording file was added to Foxglove.

importedAtstring, (date-time)

Timestamp when the recording was imported to a primary site.

startstring, (date)required

The log time of the first message in the recording.

endstring, (date)required

The log time of the last message in the recording.

importStatusstring(RecordingImportStatus)required

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 a device running Foxlet.

The set of importStatus values may expand in the future.

Enum:"none""pending""importing""failed""complete"
siteobject(PrimarySiteSummary)

The primary site for this recording.

edgeSiteobject(EdgeSiteSummary)

The edge site for this recording.

deviceobject(DeviceSummary)

ID and name of a device.

keystring

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.

metadataArray of objects(RecordingMetadata)

The metadata records of the original MCAP file content

sessionIdstring

The ID of the session this recording belongs to.

]
Response
[
  {
    "id": "string",
    "projectId": "string",
    "path": "string",
    "location": { … },
    "size": 0,
    "createdAt": "2019-08-24T14:15:22Z",
    "importedAt": "2019-08-24T14:15:22Z",
    "start": "2019-08-24",
    "end": "2019-08-24",
    "importStatus": "none",
    "site": { … },
    "edgeSite": { … },
    "device": { … },
    "key": "string",
    "metadata": [ … ],
    "sessionId": "string"
  }
]