# Alerts

## GET /api/alerts

Retrieve a list of all alerts.

### Parameters

Parameters should be passed as query parameters on the URL.

* `startTimestampAfter` - ISO 8601 date string to filter the list to only alerts sent after this time
* `alertRecipientIds` - Only query for alerts sent to specific recipient IDs. To find a recipient's ID, go to the Contact List page under Alerts and click "Edit" on the contact — the Contact ID is displayed at the bottom of the edit modal. To query for several recipient ids, use the same query parameter several times. For example, '\&alertRecipientIds=1\&alertRecipientIds=2\&alertRecipientIds=3' would query for alert recipients with IDs \[1, 2, 3].
* `includeMuted` - (Defaults to false) Filter out alerts that were not sent to users.
* `nextPageCursor` - When the filters match more than one page of data, pass this paramter to fetch the next page

### Response

The JSON response will contain a `data` field with a list of alerts matching the filters, and a `pagination` field containing pagination details.

```ts
{
  data: {
    id: number;
    type: 'lowBattery' | 'chargingCompleted' | 'chargingSessionError' | 'offlineCharger' | 'lateCharging';
    startTimestamp: string; // ISO 8601 format
    muted: boolean;
    // Alert-specific fields (only one will be populated depending on the alert type)
    lowBattery: {
      socThreshold: number | null;
      socPercent: number | null;
    } | null;
    chargingCompleted: {
      socThreshold: number | null;
      socPercent: number | null;
    } | null;
    chargingSessionError: {
      status: string | null; // Charger OCPP status -- available, etc
      ocppErrorCode: string | null;
      ocppVendorErrorCode: string | null;
      ocppInfo: string | null;
      errorContext: string | null; // Charging ended early, charging failed to start, etc
    } | null;
    offlineCharger: {
      thresholdMinutes: number | null;
    } | null;
    lateCharging: {
      originalEta: string | null; // ISO 8601 format
      currentEta: string | null; // ISO 8601 format
      originalDepartureTime: string | null; // ISO 8601 format
      currentDepartureTime: string | null; // ISO 8601 format
    } | null;
    // Additional optional details
    chargingSession: {
      id: number;
      startTime: string; // ISO 8601 format
      endTime: string | null; // ISO 8601 format
      durationSeconds: number | null;
      energyDeliveredKwh: number | null;
      socStartPercent: number | null;
      socEndPercent: number | null;
    } | null;
    site: {
      id: number;
      name: string;
      locationId: string | null;
    } | null;
    charger: {
      id: number;
      name: string;
      manufacturer: string | null;
      model: string | null;
      networkServiceProvider: string;
      chargerType: string;
      serialNumber: string | null;
      numberOfPorts: number;
      latitude: number | null;
      longitude: number | null;
      externalId: string | null;
      ocppId: string | null;
    } | null;
    port: {
      id: number;
      name: string;
      portNumber: number;
      maximumPowerKw: number | null;
    } | null;
    vehicle: {
      id: number;
      make: string | null;
      model: string | null;
      name: string | null;
      vin: string | null;
    } | null;
    organization: {
      id: number;
      name: string;
    } | null;
  }
  [];
}
```

### Example request and response

Request:

```sh
curl "https://api.getflipturn.com/api/alerts&alertRecipientIds=1&alertRecipientIds=2&startTimestampAfter=2024-04-30T01:00:07.321Z" -H "Authorization: Bearer {api_key}"
```

Response:

```js
{
  "data": [{
    "id": 123,
    "type": "lowBattery",
    "startTimestamp": "2024-04-30T01:00:07.321Z",
    "muted": false,
    "lowBattery": {
      "socThreshold": 20,
      "socPercent": 15
    },
    "chargingCompleted": null,
    "chargingSessionError": null,
    "offlineCharger": null,
    "lateCharging": null,
    "chargingSession": null,
    "site": {
      "id": 1,
      "name": "Site 1",
      "locationId": "LOC123"
    },
    "charger": {
      "id": 2,
      "name": "Main Charger",
      "manufacturer": "ABB",
      "model": "Terra 54",
      "networkServiceProvider": "Flipturn",
      "chargerType": "DCFC",
      "serialNumber": "SN123456",
      "numberOfPorts": 2,
      "latitude": 37.7749,
      "longitude": -122.4194,
      "externalId": "EXT123",
      "ocppId": "OCPP123"
    },
    "port": {
      "id": 3,
      "name": "Port A",
      "portNumber": 1,
      "maximumPowerKw": 50
    },
    "vehicle": {
      "id": 101,
      "make": "Proterra",
      "model": "ZX5",
      "name": "My Car",
      "vin": "VIN123456789"
    },
    "organization": {
      "id": 1,
      "name": "My Organization"
    }
  },
  // more items
  ],
  "pagination": {
    "hasNextPage": true,
    "nextPageCursor": "NDMyNDc2"
  }
}
```


---

# 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://api-docs.getflipturn.com/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.