> This page is for Firmware, version 3.2.
> For other versions, use one of these documentation indexes:
> - 4.0 (default): https://docs.ouster.com/sensor-docs/firmware/4.0/llms.txt
> - 3.2: https://docs.ouster.com/sensor-docs/firmware/3.2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ouster.com/sensor-docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ouster.com/sensor-docs/_mcp/server.

# Query the system for information about current and past alerts

GET http://os-992244000006.local/api/v1/sensor/alerts

Sensor diagnostic information.

Two lists will be returned, an **active** list and a **log** list. The **active** list contains a list of currently active events. The number of events in the **active** event list is unlimited.

The **log** list will contain all alert trigger and clear events. An alert-clear event has the same attributes and values as its corresponding trigger event, apart from the realtime and **cursor** attributes which will have increased, since an alert-clear event will always be received after an alert-trigger event. The **log** list has a length limit of 32 events in the form of a FIFO (First in First Out) queue. When the **log** list length limit is reached and a new event is added, the oldest event is deleted.

In addition to the **active** and **log** lists, `GET /api/v1/sensor/alerts` also returns a **next\_cursor** field. Every alert event has a **cursor** attribute, which increments for every alert event logged. This can be used to track the alert activity that has been viewed and reduce message bandwidth. To do this, users are recommended to save the **next\_cursor** field when calling `GET /api/v1/sensor/alerts` and then to use that value as the **cursor** argument on the next `GET /api/v1/sensor/alerts` call to fetch only new **log** entries.

**Additional Information:**

The **cursor** will wrap at 2^32 entries. It is important to understand the behavior during the wrap case, since this may lead to some unexpected consequences:

* If **cursor** \< (**next\_cursor** - 32) % 2^32 then some entries may be filtered. For instance if **cursor** =0 and **next\_cursor** =0 no entries will be reported immediately after **cursor** wrap, even though the log contains 32 entries, where submitting **cursor** =4294967264 (next\_cursor - 32) % 2^32 will return all logged values.

* If **cursor** > **next\_cursor** all 32 entries will be reported.
  The recommended approach to using the interface is to always base queries on the previous value of **next\_cursor**

Reference: https://docs.ouster.com/sensor-docs/firmware/api-reference/ouster-http-api/alerts-diagnostics-and-telemetry/get-alerts

## Request

### Query parameters

- `cursor` (integer, optional) — Filters the alerts to only those with __cursor__ >= query-value
- `mode` (enum, optional) — Specifies the query mode
  - Allowed values: `default`, `summary`

## Response

### 200

Successful operation

- `log` (list of AlertEntry, optional) — A log of all alerts that have occurred since the sensor was last initialized
- `next_cursor` (integer, optional) — Indicates the cursor value that will occur in the next alert to fire
- `active` (list of AlertEntry, optional) — A filtered version of `log` that lists only those alerts that are currently active

## Errors

### 400 Bad Request Error

The cursor value could not be parsed

- `any`

### 500 Internal Server Error

The sensor encountered an uncategorized internal error

- `any`

## Types

### AlertEntry

- `active` (any, optional) — true if the alert is currently active, false otherwise
- `category` (enum, optional) — determines the functional area to which the alert applies
  - Allowed values: `UNKNOWN`, `OVERTEMP`, `UNDERTEMP`, `INTERNAL_COMM`, `SHOT_LIMITING`, `INTERNAL_FW`, `ETHERNET_LINK_BAD`, `UDP_TRANSMISSION`, `STARTUP`, `INPUT_VOLTAGE`, `UDP_CONNECT`, `INTERNAL_FAULT`, `WARMUP_ISSUE`, `MOTOR_CONTROL`, `IO_CONNECTION`, `CONFIG_INVALID`, `UNEXPECTED_RUNNING_STATE_EXIT`, `MOTOR_SPEED_BAD_WARNING`, `MOTOR_SPEED_BAD`, `UNEXPECTED_MOTOR_STATE_EXIT`, `MOTOR_COIL_CHECK_FAILED`
- `cursor` (integer, optional) — The instance number of the alert, where 0 would correspond to the first alert to have occurred since the last time the sensor was initialization
- `id` (string, optional) — An internal error code that should be reported to Ouster with any related defect reports.
- `level` (enum, optional) — indicates the severity of the alert
  - Allowed values: `ERROR`, `WARNING`
- `msg` (string, optional) — ASCII text used to convey additional information about the alert
- `msg_verbose` (string, optional) — ASCII text used to convey additional information aobut the alert
- `realtime` (string, optional) — 64-bit decimal encoded timestamp

## Examples

**Response**

```json
{
  "log": [
    {
      "active": true,
      "category": "OVERTEMP",
      "cursor": 1024,
      "id": "ERR_TEMP_OVER_01",
      "level": "ERROR",
      "msg": "Sensor temperature exceeded safe operating range",
      "msg_verbose": "The internal temperature sensor reading is 95°C, exceeding the maximum threshold of 85°C. Immediate cooling required to prevent damage.",
      "realtime": "1687804800.123456"
    },
    {
      "active": false,
      "category": "OVERTEMP",
      "cursor": 1025,
      "id": "ERR_TEMP_OVER_01",
      "level": "ERROR",
      "msg": "Sensor temperature returned to normal",
      "msg_verbose": "The internal temperature sensor reading dropped to 75°C, below the critical threshold. Alert cleared.",
      "realtime": "1687808400.654321"
    }
  ],
  "next_cursor": 1026,
  "active": [
    {
      "active": true,
      "category": "ETHERNET_LINK_BAD",
      "cursor": 1026,
      "id": "WARN_ETH_LINK_03",
      "level": "WARNING",
      "msg": "Ethernet link quality degraded",
      "msg_verbose": "Packet loss detected on Ethernet interface eth0. Link speed reduced to 100Mbps from 1Gbps.",
      "realtime": "1687812000.789012"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "http://os-992244000006.local/api/v1/sensor/alerts"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'http://os-992244000006.local/api/v1/sensor/alerts';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://os-992244000006.local/api/v1/sensor/alerts"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("http://os-992244000006.local/api/v1/sensor/alerts")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("http://os-992244000006.local/api/v1/sensor/alerts")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'http://os-992244000006.local/api/v1/sensor/alerts');

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("http://os-992244000006.local/api/v1/sensor/alerts");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "http://os-992244000006.local/api/v1/sensor/alerts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```