# 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>