# List Alerts

Retrieve alerts for the authenticated user or company.

* Default: Returns only alerts owned by the authenticated user
* Company-wide: Users with `external-api-get-all-company-alerts` permission can view all authenticated user company alerts

Results are sorted by creation date (newest first). Returns an empty list with 200 OK if no alerts exist.

## Endpoint

* **URL**: `https://api.genlogs.io/alerts`
* **Method**: `GET`

## Authentication

Requires Bearer token with one of these permissions:

| Permission                            | Access                  |
| ------------------------------------- | ----------------------- |
| `external-api-get-alerts-endpoint`    | View own alerts         |
| `external-api-get-all-company-alerts` | View all company alerts |

## Headers

| Header        | Type   | Required | Description  |
| ------------- | ------ | -------- | ------------ |
| Authorization | string | Yes      | Bearer token |

## Request Example

{% code title="curl" %}

```bash
curl -X GET "https://api.genlogs.io/alerts" \
  -H "Access-Token: YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"
```

{% endcode %}

## Response (200 OK)

{% code title="application/json" %}

```json
{
  "alerts": [
    {
      "id": 35054,
      "disabled": false,
      "alert_name": "Trailer Tracking",
      "email": "user@company.com",
      "cc_emails": null,
      "start_date": "2026-01-19T05:00:00",
      "end_date": "2026-01-19T05:00:00",
      "location_state": null,
      "location_city": null,
      "license_plate": null,
      "license_plate_state": null,
      "usdot_number": null,
      "mc_number": null,
      "chassis_number": null,
      "container_number": null,
      "exact_match_chassis_number": false,
      "exact_match_container_number": false,
      "vin": null,
      "cab_number": null,
      "equipment_type": null,
      "trailer_logo": null,
      "trailer_number": null,
      "alert_type": "hot",
      "exact_match_trailer_number": false,
      "deep_search": "fx",
      "exact_match_deep_search": false,
      "notification_channels": ["WEBHOOK", "EMAIL"],
      "create_date": "2026-01-19T13:00:39.177379"
    },
    {
      "id": 34547,
      "disabled": false,
      "alert_name": "Fleet Monitor",
      "email": "user@company.com",
      "cc_emails": null,
      "start_date": "2025-11-01T00:00:00",
      "end_date": "2025-11-01T00:00:00",
      "location_state": null,
      "location_city": null,
      "license_plate": null,
      "license_plate_state": null,
      "usdot_number": null,
      "mc_number": null,
      "chassis_number": null,
      "container_number": null,
      "exact_match_chassis_number": null,
      "exact_match_container_number": null,
      "vin": null,
      "cab_number": null,
      "equipment_type": null,
      "trailer_logo": null,
      "trailer_number": null,
      "alert_type": "normal",
      "exact_match_trailer_number": false,
      "deep_search": "az",
      "exact_match_deep_search": false,
      "notification_channels": ["EMAIL"],
      "create_date": "2026-01-08T22:32:41.609945"
    },
    ...
  ]
}
```

{% endcode %}

## Response Fields

| Field                           | Type     | Description                                  |
| ------------------------------- | -------- | -------------------------------------------- |
| id                              | integer  | Unique alert identifier                      |
| disabled                        | boolean  | Whether the alert is disabled                |
| alert\_name                     | string   | Name of the alert                            |
| email                           | string   | Email of the alert owner                     |
| cc\_emails                      | array    | List of CC email addresses for notifications |
| start\_date                     | datetime | Alert start date (ISO 8601)                  |
| end\_date                       | datetime | Alert end date (ISO 8601)                    |
| location\_state                 | string   | State filter for sightings                   |
| location\_city                  | string   | City filter for sightings                    |
| license\_plate                  | string   | License plate to search                      |
| license\_plate\_state           | string   | State of the license plate                   |
| usdot\_number                   | string   | USDOT number to search                       |
| mc\_number                      | string   | MC number to search                          |
| chassis\_number                 | string   | Chassis number to search                     |
| container\_number               | string   | Container number to search                   |
| exact\_match\_chassis\_number   | boolean  | Require exact match for chassis number       |
| exact\_match\_container\_number | boolean  | Require exact match for container number     |
| vin                             | string   | VIN to search                                |
| cab\_number                     | string   | Cab number to search                         |
| equipment\_type                 | string   | Equipment type to search                     |
| trailer\_logo                   | string   | Trailer logo identifier                      |
| trailer\_number                 | string   | Trailer number to search                     |
| alert\_type                     | string   | Alert type: `hot` or `normal`                |
| exact\_match\_trailer\_number   | boolean  | Require exact match for trailer number       |
| deep\_search                    | string   | Deep search query                            |
| exact\_match\_deep\_search      | boolean  | Require exact match for deep search          |
| notification\_channels          | array    | Notification methods: `EMAIL`, `WEBHOOK`     |
| create\_date                    | datetime | Creation timestamp                           |

## Error Responses

<details>

<summary>Possible error responses</summary>

| Status | Description                             |
| ------ | --------------------------------------- |
| 401    | Unauthorized - Invalid or missing token |
| 403    | Forbidden - Missing required permission |
| 500    | Internal Server Error                   |

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.genlogs.io/alerts/list-alerts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.