# Charging Sessions ## GET /api/charging-sessions Retrieve a list of completed charging sessions. ### Parameters Parameters should be passed as query parameters on the URL. * `startTimeAfter` - ISO 8601 date string to filter the list to only sessions started at or after this time * `startTimeBefore` - ISO 8601 date string to filter the list to only sessions started before this time * `endTimeAfter` - ISO 8601 date string to filter the list to only sessions ended at or after this time * `endTimeBefore` - ISO 8601 date string to filter the list to only sessions ended before this time * `nextPageCursor` - When the filters match more than one page of data, pass this paramter to fetch the next page * `includeIntervals` - Returns additional data about the charging session: max demand for the entire session, along with statistics for each 15-minute charging interval. When this parameter is included, an individual api key is limited to 1 concurrent request at a time. * `includeTouEnergy` - Returns energy usage grouped into time of use periods for each session * `includeInProgressSessions` - Returns charging sessions that are in progress * `siteIds` - Site IDs, which can be retrieved from the /sites endpoint, to filter for. To pass multiple site IDs, add them to the query parameters like this: `siteIds[]=101&siteIds[]=102` * `chargerIds` - Charger IDs, which can be retrieved from the /sites endpoint, to filter for. To pass multiple site IDs, add them to the query parameters like this: `chargerIds[]=101&chargerIds[]=102` * `customerIds` - Customer IDs to filter for. To pass multiple customer IDs, add them to the query parameters like this: `customerIds[]=101&customerIds[]=102` * `customerNames` - Customer names to filter for. To pass multiple customer names, add them to the query parameters like this: `customerNames[]=Acme%20Corp&customerNames[]=Fleet%20Inc` ### Response The JSON response will contain a `data` field with a list of charging sessions matching the filters, and a `pagination` field containing pagination details. ```ts { data: { id: number; startTime: string; // ISO 8601 format updatedAt: string; // ISO 8601 format socStartPercent: number | null; socEndPercent: number | null; maxDemandKw: number | null; ocppIdTag: string | null; tags: string[]; chargingStartTime: string; // ISO 8601 format, see "Charging time fields" note below // The following fields are nullable on in progress charging sessions endTime: string | null; // ISO 8601 format durationSeconds: number | null; energyDeliveredKwh: number | null; averageDemandKw: number | null; chargingEndTime: string | null; // ISO 8601 format, see "Charging time fields" note below chargingDurationSeconds: number | null; // The duration in seconds between chargingStartTime and chargingEndTime, see "Charging time fields" note below // Only defined if includeIntervals=true and charging session is ended. Session statistics, grouped into 15-minute intervals. intervals: { id: string; intervalStartTime: string; // ISO 8601 format intervalEndTime: string; // ISO 8601 format socStartPercent: number | null; socEndPercent: number | null; energyDeliveredKwh: number; maxDemandKw: number; averageDemandKw: number; }[] | null; // Only defined if includeTouEnergy=true. Energy usage grouped into time-of-use period buckets. touEnergy: { timeOfUsePeriodName: string; energyKwh: number; }[] | null; site: { id: number; name: string; locationId: string | null; // A unique identification number for a site, provided by a utility }; 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; }; port: { id: number; name: string; portNumber: number; maximumPowerKw: number | null; }; vehicle: { id: number; name: string | null; vin: string | null; make: string | null; model: string | null; } | null; rfid: { id: number; name: string | null; } | null; customer: { name: string } | null; organization: { id: number; name: string; }; ocppTransactionId: number | null; // The ID reported from the charger to identify messages related to the charging session }[]; pagination: { hasNextPage: boolean; nextPageCursor: string | null; }; }; ``` ### Example request and response Request: ```sh curl "https://api.getflipturn.com/api/charging-sessions?startTimeAfter=2023-03-24T01:18:05.000Z&includeIntervals=true" -H "Authorization: Bearer {api_key}" ``` Response: ```js { "data": [ { "id": 428177, "startTime": "2023-08-29T22:57:46.479Z", "endTime": "2023-08-30T01:00:07.321Z", "updatedAt": "2023-08-30T01:00:07.321Z", "durationSeconds": 7341, "chargingStartTime": "2023-08-29T22:57:46.479Z", "chargingEndTime": "2023-08-30T00:45:00.000Z", "chargingDurationSeconds": 6441, "socStartPercent": 14, "socEndPercent": 50, "energyDeliveredKwh": 78.775, "averageDemandKw": 10.0, "maxDemandKw": 12, "intervals": [...], "ocppIdTag": "demo-id-tag-0", "tags": ['ABC Trucking', 'XYZ Trucking'], "site": { "id": 13, "name": "Long Beach", "locationId": null }, "charger": { "id": 53, "name": "Long Beach 1", "manufacturer": "ABB", "model": "AC Wall Box", "networkServiceProvider": "Flipturn", "chargerType": "DCFC", "numberOfPorts": 1, "serialNumber": "DEMO-NUMBER", "latitude": 1.0, "longitude": 1.0, "externalId": "STATION-001", "ocppId": "CHARGER-001" }, "port": { "id": 650244, "name": "Port 1", "portNumber": 1, "maximumPowerKw": 180}, "vehicle": { "id": 22541553, "make": "Make", "model": "Model", "name": "9876", "vin": "demo-vin-0" }, "customer": { "name": "Electric Fleet Transportation" }, "organization": { "id": 1, "name": "Fleet Management Corp" } } ], "pagination": { "hasNextPage": true, "nextPageCursor": "NDMyNDc2" } } ``` #### Charging time fields Some utility reporting programs require reporting not just the start/end of the session, but also the time during which energy was actually delivered. The following fields provide this information: * `chargingStartTime` - The time when energy started being delivered * `chargingEndTime` - The time when energy stopped being delivered * `chargingDurationSeconds` - The duration during which energy was delivered, in seconds ## Synchronizing charging sessions into an external system If your goal is to continuously import charging sessions into a system like a data warehouse, you may set up a recurring job to import any new charging sessions that are in Flipturn. It's important to ensure that you don't double insert any charging sessions or miss one. We recommend splitting this into two phases: * Backfill all historical sessions * Poll for new sessions ### Backfill all historical sessions In order to export all sessions, the first request to the charging sessions endpoint should have no filter parameters. Then, every subsequent request will take the `nextPageCursor` from the prior response and add that to the next request. Assume the first request returned: ```js { "data": [ { // 20 items }, ] "pagination": { "hasNextPage": true, "nextPageCursor": "NDMyNDc2" } } ``` The second request should look like: ``` /api/charging-sessions?nextPageCursor=NDMyNDc2 ``` Repeat this process until you receive a response where `pagination.hasNextPage` is false. ### Poll for new sessions Once all the historical sessions have been exported, you can continually poll the API to fetch sessions that have completed since the last request. Each request, you should keep track of the latest `endTimestamp` you've seen so far, and pass that in to `endTimeAfter`: ``` /api/charging-sessions?endTimeAfter=2023-08-30T01:00:07.321Z ``` #### Avoiding double-inserting Instead of keeping track of the latest `endTimestamp`, some users might prefer to generate an `endTimeAfter` relative to when they're sending the request. For example, if you poll for new sessions every 30s, each request could set `endTimeAfter` to a timestamp slightly more than 30s ago to account for clock skew. However, one risk of this buffer is it's possible to see a session that you've already exported. To help deduplicate, each charging session has a unique `id`, so it's recommended to use this as a unique key to ensure you don't insert the same charging session twice. --- # 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/charging-sessions.md?ask= ``` 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.