# Code Samples for the Chrome Management Telemetry API

Visit
[Chrome Management Telemetry API](https://developers.google.com/chrome/management/guides/telemetry_api)
for an overview of API features.

All the requests shown below use the following variables:

- `$TOKEN` - OAuth 2 token
- `$CUSTOMER` - ID of the customer or literal `my_customer`

## List Telemetry Device Data

To list telemetry data for a chrome device use the
`/telemetry/devices` endpoint. The `readMask` parameter is used to specify which
device fields are returned. You can control pagination of the results using the
`pageSize` and `pageToken` parameters. Specify a `filter` to further narrow down
the results based off of device or report criteria.

> [!NOTE]
> **Note:** The `readMask` parameter is **required** for list requests. Only fields specified in the mask will be returned in the response. Also, requests that don't specify a `reports_timestamp` in the `filter` parameter will only return **recent report data** . Include `reports_timestamp>=0` in the request to retrieve all report data.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/devices?readMask=name,customer,orgUnitId,deviceId,serialNumber,cpuInfo,cpuStatusReport,memoryInfo,memoryStatusReport,osUpdateStatus&pageSize=2"

#### Response

    {
      "devices": [
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "deviceId": "<deviceId>",
          "serialNumber": "0A2B213CDEFG",
          "cpuStatusReport": [
            {
              "reportTime": "2021-04-25T13:23:55.880Z",
              "cpuUtilizationPct": 76
            },
            {
              "reportTime": "2021-04-25T18:25:55.880Z",
              "cpuTemperatureInfo": [
                {
                  "temperatureCelsius": 38,
                  "label": "Core"
                },
              ]
            }
          ],
          "memoryStatusReport": [
            {
              "reportTime": "2021-04-25T13:23:55.880Z",
              "systemRamFreeBytes": "14358468900"
            }
          ],
          "osUpdateStatus": [
            {
              "lastUpdateTime": "2021-04-25T11:18:51.383Z",
              "lastUpdateCheckTime": "1970-01-01T00:00:00Z",
              "lastRebootTime": "2021-04-25T11:18:51.383Z"
            }
          ]
        },
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId>",
          "customer": "customers/<customer>",
          "orgUnitId": "FEDCBA",
          "deviceId": "<deviceId>",
          "serialNumber": "1B3D817LKUH",
          "cpuStatusReport": [
            {
              "reportTime": "2021-05-25T13:23:55.880Z",
              "cpuUtilizationPct": 50
            },
          ],
          "memoryStatusReport": [
            {
              "reportTime": "2021-05-25T13:23:55.880Z",
              "systemRamFreeBytes": "14358468900"
            }
          ],
          "osUpdateStatus": [
            {
              "lastUpdateTime": "2021-05-25T11:18:51.383Z",
              "lastUpdateCheckTime": "1970-01-01T00:00:00Z",
              "lastRebootTime": "2021-05-25T11:18:51.383Z"
            }
          ]
        }
      ],
      "nextPageToken": "PAGE_TOKEN"
    }

## List Telemetry Device Data for a Single Org Unit

To list telemetry data for a single org unit, use the `orgUnitId` value in the `filter` parameter.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/devices?readMask=name,customer,orgUnitId,deviceId,serialNumber,cpuInfo,cpuStatusReport,memoryInfo,memoryStatusReport,osUpdateStatus&filter=orgUnitId=ABCDEFG"

#### Response

    {
      "devices": [
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "deviceId": "<deviceId>",
          "serialNumber": "0A2B213CDEFG",
          "cpuStatusReport": [
            {
              "reportTime": "2021-04-25T13:23:55.880Z",
              "cpuUtilizationPct": 76
            },
            {
              "reportTime": "2021-04-25T18:25:55.880Z",
              "cpuTemperatureInfo": [
                {
                  "temperatureCelsius": 38,
                  "label": "Core"
                },
              ]
            }
          ],
          "memoryStatusReport": [
            {
              "reportTime": "2021-04-25T13:23:55.880Z",
              "systemRamFreeBytes": "14358468900"
            }
          ],
          "osUpdateStatus": [
            {
              "lastUpdateTime": "2021-04-25T11:18:51.383Z",
              "lastUpdateCheckTime": "1970-01-01T00:00:00Z",
              "lastRebootTime": "2021-04-25T11:18:51.383Z"
            }
          ]
        }
      ]
    }

## List Telemetry Device Data Using a Timestamp Filter

The timestamp filter returns all devices, but only includes reports that conform
to the timestamp filter and specified `read_mask`.

To use this filter, specify the `reports_timestamp` value in the `filter`
parameter and include a timestamp value in either the Unix Epoch in milliseconds
(ie. `1679288169623`) or RFC 3339 "Zulu" formatted time (up to nine fractional
digits ie. `"2023-02-15T11:18:51.383Z"`) formats. Timestamps returned by the
API are in the UTC timezone, so `reports_timestamp` filter values should also be
in the UTC timezone. All standard number comparison operators
(`<, >, <=, >=, =`) are supported.

> [!NOTE]
> **Note:** Requests without an explicit `reports_timestamp` filter will only return **recent report data** . Include `reports_timestamp>=0` in the request to retrieve all report data.

### List All Reports

Since only recent reports are returned when no `reports_timestamp` value is
specified, the following call can be used to retrieve all device reports
included in the `read_mask` for all devices.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/devices?readMask=name,customer,orgUnitId,deviceId,serialNumber,audioStatusReport,cpuStatusReport,heartbeatStatusReport,memoryStatusReport&filter=reports_timestamp>=0"

#### Response

    {
      "devices": [
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "deviceId": "<deviceId>",
          "serialNumber": "0A2B213CDEFG",
          "audioStatusReport": [
            {
              "reportTime": "2009-01-01T12:37:51.383Z",
              "inputMute": true,
              "inputDevice": "example input device 2009",
            },
            {
              "reportTime": "2010-02-01T12:37:51.383Z",
              "inputMute": false,
              "inputDevice": "example input device 2010",
            },
            {
              "reportTime": "2011-03-01T12:37:51.383Z",
              "inputMute": true,
              "inputDevice": "example input device 2011",
            },
            {
              "reportTime": "2024-01-01T12:37:51.383Z",
              "inputMute": false,
              "inputDevice": "example input device 2024",
            }
          ],
          "cpuStatusReport": [
            {
              "reportTime": "1960-10-15T01:18:51.383Z",
              "cpuUtilizationPct": 76
            },
            {
              "reportTime": "1997-10-31T11:18:51.383Z",
              "cpuTemperatureInfo": [
                {
                  "temperatureCelsius": 38,
                  "label": "Core"
                },
              ]
            }
          ]
        },
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId 1>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "deviceId": "<deviceId 1>",
          "serialNumber": "HGFEDCBA",
          "heartbeatStatusReport": [
            {
              "reportTime": "2001-02-15T11:18:51.383Z",
              "state": "ONLINE"
            },
            {
              "reportTime": "2002-07-22T11:18:51.383Z",
              "state": "OFFLINE"
            },
            {
              "reportTime": "2012-01-04T11:18:51.383Z",
              "state": "UNKNOWN"
            },
            {
              "reportTime": "2024-02-29T11:18:51.383Z",
              "state": "ONLINE"
            }
          ],
          "memoryStatusReport": [
            {
              "reportTime": "2024-03-20T11:18:51.383Z",
              "systemRamFreeBytes": "112233445566778"
            }
          ]
        }
      ]
    }

### List Reports After A Specific Timestamp

To make a request for querying reports after a specific timestamp, use the
`reports_timestamp` as is shown in the following example.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/devices?readMask=name,customer,orgUnitId,deviceId,serialNumber,cpuStatusReport,memoryStatusReport,osUpdateStatus&filter=reports_timestamp>=\"2023-02-15T11:18:51.383Z\""

#### Response

    {
      "devices": [
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "deviceId": "<deviceId>",
          "serialNumber": "0A2B213CDEFG",
          "cpuStatusReport": [
            {
              "reportTime": "2023-02-15T11:18:51.383Z",
              "cpuUtilizationPct": 76
            },
            {
              "reportTime": "2023-03-19T11:18:51.383Z",
              "cpuTemperatureInfo": [
                {
                  "temperatureCelsius": 38,
                  "label": "Core"
                },
              ]
            }
          ],
          "memoryStatusReport": [
            {
              "reportTime": "2023-04-19T11:18:51.383Z",
              "systemRamFreeBytes": "14358468900"
            }
          ]
        },
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId 1>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "deviceId": "<deviceId 1>",
          "serialNumber": "HGFEDCBA",
          "memoryStatusReport": [
            {
              "reportTime": "2024-02-15T11:18:51.383Z",
              "systemRamFreeBytes": "112233445566778"
            }
          ]
        }
      ]
    }

> [!NOTE]
> **Note:** If there are no corresponding reports that conform to the time filter, the report will not be populated on the device, even if it is requested (as shown above with `osUpdateStatus`).

## List Telemetry Device Data Using Multiple Filters (Conjunction Filtering)

To use multiple filters to narrow down the response returned by the api, use the `AND` keyword in the `filter` parameter and include multiple filtering criteria.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/devices?readMask=name,customer,orgUnitId,deviceId,serialNumber,cpuStatusReport,memoryStatusReport,osUpdateStatus&filter=reports_timestamp=\"2023-02-15T11:18:51.383Z\" AND serialNumber=HGFEDCBA"

#### Response

    {
      "devices": [
        {
          "name": "customers/<customer>/telemetry/devices/<deviceId 1>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "deviceId": "<deviceId 1>",
          "serialNumber": "HGFEDCBA",
          "memoryStatusReport": [
            {
              "reportTime": "2023-02-15T11:18:51.383Z",
              "systemRamFreeBytes": "112233445566778"
            }
          ]
        }
      ]
    }

## List Telemetry User Data

To list telemetry data for a chrome device use the
`/telemetry/users` endpoint. The `readMask` parameter is used to specify which
device fields are returned. You can control pagination of the results using the
`pageSize` and `pageToken` parameters.

> [!NOTE]
> **Note:** The `readMask` parameter is **required** for list requests. Only fields specified in the mask will be returned in the response.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/users?readMask=name,customer,orgUnitId,userId,userEmail,user_device.device_id,user_device.audio_status_report,user_device.peripherals_report&pageSize=2"

#### Response

    {
      "telemetryUsers": [
        {
          "name": "customers/<customer>/telemetry/users/<userId>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "userEmail": "<userId>",
          "userEmail": "user@mytestdomain.com",
          "userDevice": [
            {
              "deviceId": "HIJKLMNOP",
              "audioStatusReport": [
                {
                  "reportTime": "2021-04-25T13:23:55.880Z",
                  "outputMute": true,
                  "inputMute": true,
                }
              ],
              "peripheralsReport": [
                {
                  "reportTime": "2021-04-25T18:25:55.880Z",
                  "usbPeripheralReport": [
                    {
                      "vendor": "Vendor",
                      "name": "Microphone",
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "name": "customers/<customer>/telemetry/users/<userId>",
          "customer": "customers/<customer>",
          "orgUnitId": "QRSTUV",
          "userEmail": "<userId>",
          "userEmail": "user2@mytestdomain.com",
          "userDevice": [
            {
              "deviceId": "WXYZ",
              "audioStatusReport": [
                {
                  "reportTime": "2021-04-25T13:23:55.880Z",
                  "outputMute": true,
                  "inputMute": true,
                }
              ],
              "peripheralsReport": [
                {
                  "reportTime": "2021-04-25T18:25:55.880Z",
                  "usbPeripheralReport": [
                    {
                      "vendor": "Vendor",
                      "name": "Microphone",
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "nextPageToken": "PAGE_TOKEN"
    }

## List Telemetry User Data for a Single Org Unit

To list telemetry data for a single org unit, use the `orgUnitId` value in the `filter` parameter.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/users?readMask=name,customer,orgUnitId,userId,userEmail,user_device.device_id,user_device.audio_status_report,user_device.peripherals_report&pageSize=2&filter=orgUnitId=ABCDEFG"

#### Response

    {
      "telemetryUsers": [
        {
          "name": "customers/<customer>/telemetry/users/<userId>",
          "customer": "customers/<customer>",
          "orgUnitId": "ABCEDFG",
          "userEmail": "<userId>",
          "userEmail": "user@mytestdomain.com",
          "userDevice": [
            {
              "deviceId": "HIJKLMNOP",
              "audioStatusReport": [
                {
                  "reportTime": "2021-04-25T13:23:55.880Z",
                  "outputMute": true,
                  "inputMute": true,
                }
              ],
              "peripheralsReport": [
                {
                  "reportTime": "2021-04-25T18:25:55.880Z",
                  "usbPeripheralReport": [
                    {
                      "vendor": "Vendor",
                      "name": "Microphone",
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }

## List Telemetry Event Data

To list telemetry events for a customer, use the `/telemetry/events` endpoint. The `readMask` parameter is used to specify which fields are returned. In the near future, the `readMask` parameter will become optional, and the `filter`
param with at least 1 event type will be required.

By default, the event's `name`, `report_time`, and `event_type` fields are included in the response. You can control pagination of the results using the `pageSize` and `pageToken` parameters. Additionally, you can filter results with the following parameters:

- device_id
- user_id
- device_org_unit_id
- user_org_unit_id
- timestamp
  - Input value can either be EPOCH milliseconds, ie `timestamp<1667423821001` or RFC 3339, ie. `timestamp<"2022-11-02T20:08:32.386Z"`
- event_type
  - audio_severe_underrun
  - network_connection_state_change
  - usb_added
  - usb_removed
  - network_htps_latency_change

> [!NOTE]
> **Note:** Although the `readMask` parameter is **currently required** for list requests, it will be optional in the near future while the `filter` parameter with at least 1 event type specified **will be required**. Only fields specified in the mask or event type filter will be returned in the response.

#### Request

      curl -X GET \
      -H "Authorization: Bearer $TOKEN" \
      "https://chromemanagement.googleapis.com/v1/customers/$CUSTOMER/telemetry/events?readMask=device,usb_peripherals_event&filter=event_type=usb_added&pageSize=3"

#### Response

    {
      "telemetryEvents": [
        {
          "name": "customers/<customer>/telemetry/events/<event id>",
          "device": {
            "deviceId": "<device id>",
            "orgUnitId": "<device's org unit id>"
          },
          "reportTime": "2022-11-02T11:14:09.034Z",
          "eventType": "USB_ADDED",
          "usbPeripheralsEvent": {
            "usbPeripheralReport": [
              {
                "vendor": "Microdia",
                "name": "Integrated_Webcam_HD",
                "vid": <vid>,
                "pid": <pid>
              }
            ]
          }
        },
        {
          "name": "customers/<customer>/telemetry/events/<event id>",
          "device": {
            "deviceId": "<device id>",
            "orgUnitId": "<device's org unit id>"
          },
          "reportTime": "2022-11-02T10:10:36.481Z",
          "eventType": "USB_ADDED",
          "usbPeripheralsEvent": {
            "usbPeripheralReport": [
              {
                "vendor": "Hewlett-Packard",
                "name": "x304m",
                "vid": <vid>,
                "pid": <pid>,
                "categories": [
                  "Mass storage"
                ]
              }
            ]
          }
        },
        {
          "name": "customers/<customer>/telemetry/events/<event id>",
          "device": {
            "deviceId": "<device id>",
            "orgUnitId": "<device's org unit id>"
          },
          "reportTime": "2022-11-02T09:58:48.249Z",
          "eventType": "USB_ADDED",
          "usbPeripheralsEvent": {
            "usbPeripheralReport": [
              {
                "vendor": "Realtek Semiconductor Corp.",
                "name": "USB 10/100/1000 LAN",
                "vid": <vid>,
                "pid": <pid>,
                "categories": [
                  "Vendor Specific"
                ]
              }
            ]
          }
        }
      ],
      "nextPageToken": "<page token>"
    }