> For the complete documentation index, see [llms.txt](https://api-docs.getflipturn.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.getflipturn.com/charger-health.md).

# Charger Health

## GET /api/charger-health

Retrieve health, uptime, error, and utilization statistics for all chargers in an organization, grouped by charger and port, over a specified time interval. This endpoint is useful for generating reliability and performance reports for your charging infrastructure.

### Parameters

Parameters should be passed as query parameters on the URL.

* `startTimestamp` (optional) - ISO 8601 date string with optional timezone offset. Start of the interval to analyze. Defaults to 30 days before the current time if not provided.
* `endTimestamp` (optional) - ISO 8601 date string with optional timezone offset. End of the interval to analyze. Defaults to the current time if not provided. If a future date is provided, it will be capped at the current time.
* `siteIds` (optional) - Array of site IDs to filter for. To pass multiple site IDs, add them to the query parameters like this: `siteIds[]=101&siteIds[]=102`.
* `chargerIds` (optional) - Array of charger IDs to filter for. To pass multiple charger IDs, add them to the query parameters like this: `chargerIds[]=201&chargerIds[]=202`.

### Response

The JSON response contains a `summary` field with aggregate statistics for the interval, and a `data` field with per-charger and per-port statistics.

A few notes:

* `activeTimeInIntervalSeconds` may be less than the total interval if the charger was activated after the start of the interval -- for example, if you select the month of June but the charger first came online on June 15, all of the statistics will be based on the second half of the month (instead of starting out immediately for 50% downtime).
* Error counts are grouped by type: `endedEarly` (charging stopped before expected), `failedToStart` (charging could not begin), and `other` (miscellaneous or unknown errors).
* The uptime seconds for a charger are the sum of the uptime across the ports, so the uptime can be longer than the actual length of the interval. As an example, if you select 2 weeks of data for a 2-port charger, the total uptime could be 4 weeks if both ports were up the whole time.

```ts
{
  summary: {
    startTime: string; // ISO 8601 format
    endTime: string; // ISO 8601 format
    errorCounts: {
      endedEarly: number;
      failedToStart: number;
      other: number;
      total: number;
    }
    chargingSessionsCount: number;
    uptime: {
      faultedSeconds: number;
      availableSeconds: number;
      unavailableSeconds: number;
      uptimePercent: number;
    }
  }
  data: Array<{
    chargerId: number;
    serialNumber: string | null;
    name: string;
    manufacturer: string | null; // Charger manufacturer, or null if unknown
    activeTimeInIntervalSeconds: number; // May be less than the interval if charger was activated after start
    site: {
      id: number;
      name: string;
    };
    connectivity: {
      onlineSeconds: number;
      offlineSeconds: number;
      onlinePercent: number;
    };
    maintenance: {
      maintenanceSeconds: number;
      maintenancePercent: number;
    };
    uptime: {
      faultedSeconds: number;
      availableSeconds: number;
      unavailableSeconds: number;
      uptimePercent: number;
    };
    utilization: {
      chargingSessionSeconds: number;
      utilizationPercent: number;
    };
    errorCounts: {
      endedEarly: number;
      failedToStart: number;
      other: number;
      total: number;
    };
    chargingSessionsCount: number;
    reportUrl: string;
    ports: Array<{
      id: number;
      name: string;
      uptime: {
        faultedSeconds: number;
        availableSeconds: number;
        unavailableSeconds: number;
        uptimePercent: number;
      };
      utilization: {
        chargingSessionSeconds: number;
        utilizationPercent: number;
      };
      errorCounts: {
        endedEarly: number;
        failedToStart: number;
        other: number;
        total: number;
      };
      chargingSessionsCount: number;
    }>;
  }>;
}
```

### Example request and response

Request:

```sh
curl "https://api.getflipturn.com/api/charger-health?startTimestamp=2024-07-01T00:00:00.000Z&endTimestamp=2024-07-31T23:59:59.999Z" -H "Authorization: Bearer {api_key}"
```

Response:

```js
{
  "summary": {
    "startTime": "2024-07-01T00:00:00.000Z",
    "endTime": "2024-07-31T23:59:59.999Z",
    "errorCounts": {
      "endedEarly": 2,
      "failedToStart": 1,
      "other": 0,
      "total": 3
    },
    "chargingSessionsCount": 42,
    "uptime": {
      "faultedSeconds": 2400,
      "availableSeconds": 5180000,
      "unavailableSeconds": 16000,
      "uptimePercent": 99.5
    }
  },
  "data": [
    {
      "chargerId": 101,
      "serialNumber": "FT-CHARGER-0001",
      "name": "Main Charger",
      "manufacturer": "Example Manufacturer",
      "activeTimeInIntervalSeconds": 2678400,
      "site": {
        "id": 1,
        "name": "Site 1"
      },
      "connectivity": {
        "onlineSeconds": 2600000,
        "offlineSeconds": 78400,
        "onlinePercent": 97.1
      },
      "maintenance": {
        "maintenanceSeconds": 3600,
        "maintenancePercent": 0.13
      },
      "uptime": {
        "faultedSeconds": 1200,
        "availableSeconds": 2590000,
        "unavailableSeconds": 8000,
        "uptimePercent": 99.6
      },
      "utilization": {
        "chargingSessionSeconds": 120000,
        "utilizationPercent": 4.6
      },
      "errorCounts": {
        "endedEarly": 1,
        "failedToStart": 1,
        "other": 0,
        "total": 2
      },
      "chargingSessionsCount": 20,
      "reportUrl": "https://cloud.getflipturn.com/o/99/reports/charger-health/chargers/101",
      "ports": [
        {
          "id": 201,
          "name": "Port 1",
          "uptime": {
            "faultedSeconds": 600,
            "availableSeconds": 1295000,
            "unavailableSeconds": 4000,
            "uptimePercent": 99.7
          },
          "utilization": {
            "chargingSessionSeconds": 60000,
            "utilizationPercent": 4.6
          },
          "errorCounts": {
            "endedEarly": 1,
            "failedToStart": 0,
            "other": 0,
            "total": 1
          },
          "chargingSessionsCount": 10
        }
      ]
    }
  ]
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://api-docs.getflipturn.com/charger-health.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
