Skip to main content

Telemetry Export

For supported devices (a6, a7, a8, oven_v1, oven_v2), you can export historical telemetry data.

Command Structure​

To export telemetry data from an Anova device, clients must send a websocket command with the following structure:

{
  "command": "CMD_EXPORT_TELEMETRY",
  "requestId": "[UUID]",
  "payload": {
    "id": "[UUID]",
    "type": "CMD_EXPORT_TELEMETRY",
    "payload": {
      "deviceId": "[your-device-id]",
      "startTime": "YYYY-MM-DD",
      "endTime": "YYYY-MM-DD"
    }
  }
}

Example:

{
  "command": "CMD_EXPORT_TELEMETRY",
  "requestId": "telemetry-export-123456",
  "payload": {
    "id": "unique-id-for-payload",
    "type": "CMD_EXPORT_TELEMETRY",
    "payload": {
      "deviceId": "your-device-id",
      "startTime": "2025-04-13",
      "endTime": "2025-05-13"
    }
  }
}

Parameters:

  • command: Must be "CMD_EXPORT_TELEMETRY" (required)
  • requestId: A unique identifier for the request, should be a UUID (required)
  • payload.id: A unique identifier for the nested payload, should be a UUID (required)
  • payload.type: Must be "CMD_EXPORT_TELEMETRY" (required)
  • payload.payload.deviceId: The ID of the device to export data for (required)
  • payload.payload.startTime: Start date in YYYY-MM-DD format (required)
  • payload.payload.endTime: End date in YYYY-MM-DD format (required)

Time and Date Restrictions​

The export telemetry feature has several important time and date restrictions:

  1. Date Format: Dates must be in YYYY-MM-DD format (e.g., "2025-04-13")
  2. Historical Limit: Start date cannot be more than 90 days in the past
  3. Future Dates: End date cannot be in the future
  4. Valid Range: End date must be after start date
  5. Maximum Range: Date range cannot exceed 14 days

Response Structure and File Format​

Success Response​

A successful export will return:

{
  "command": "RESPONSE",
  "requestId": "telemetry-export-123456",
  "payload": {
    "status": "ok",
    "data": {
      "message": "Success! Check downloadUrls for results",
      "downloadUrls": [
        "https://url-to-file-1.csv.gz",
        "https://url-to-file-2.csv.gz"
      ],
      "deviceId": "your-device-id",
      "startTime": "2025-04-13",
      "endTime": "2025-05-13"
    }
  }
}

File Format Details:​

  • Files are provided as CSV (Comma-Separated Values) with gzip compression (.csv.gz)
  • Files include a header row with column names
  • Data is sorted chronologically (ascending by time)
  • Download URLs expire after 1 hour from generation

Limitations, Errors, and Best Practices​

Limitations:​

  • Maximum date range of 14 days per request
  • Historical data limited to 90 days in the past
  • Download URLs expire after 1 hour
  • Telemetry export only works for the following devices: a6, a7, a8, oven_v1, oven_v2

Possible Error Responses:​

  • 400: Missing or invalid parameters, date format issues, time range violations
  • 401: Unauthorized (user does not have access to requested device)
  • 404: No data found for the specified time range and device
  • 429: Export request throttled (rate limiting)
  • 500: Internal server error