> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionage.in/llms.txt
> Use this file to discover all available pages before exploring further.

# List sessions

> Returns charging sessions linked to customers. Sessions that cannot be associated with a customer are excluded.



## OpenAPI

````yaml /api-reference/nexus/nexus-api-oas.json get /sessions
openapi: 3.0.3
info:
  title: Nexus API
  description: >-
    The Nexus API provides access to charging stations, chargers, connectors,
    tariffs, customers, and charging sessions for partner backend integrations.


    ## Integration model


    This API is designed for server-to-server use. End-user applications should
    access this data through the partner backend rather than calling these
    endpoints directly.


    ## Authentication


    Every request must include an `x-api-key` header containing a valid API key.
    Missing or unrecognized API keys are rejected with `401 Unauthorized`.


    ## IDs


    Stations, chargers, and tariffs use `id` as their public stable identifier.
    These identifiers are exactly 8 alphanumeric characters. Customers use `id`,
    an opaque identifier supplied by the partner system. Sessions use a numeric
    session ID. Connector IDs are 1-based positive integers within a charger;
    invalid connector path values return `404 Not Found`.


    ## Tariffs


    Tariffs use a structured pricing model with elements, price components, and
    optional restrictions. `tariffId` response fields reference public tariff
    identifiers and are omitted when no tariff applies.


    ## Pagination


    Paginated collection endpoints accept `limit` and `offset` query parameters.
    Missing, non-integer, zero, or negative `limit` values use the default limit
    of 100; values above 100 are clamped to 100. Missing, non-integer, or
    negative `offset` values use 0. The response body includes a `links` object
    with `next` and `prev` URLs. A link is `null` when that page does not exist.
    The total result count is returned in the `X-Total-Count` response header.
  version: 1.0.0
servers:
  - url: https://{host}/v1
    description: Environment-specific Nexus API base URL.
    variables:
      host:
        default: api.example.com
        description: Nexus API host provided during onboarding.
security:
  - ApiKeyAuth: []
tags:
  - name: Stations
  - name: Chargers
  - name: Connectors
  - name: Tariffs
  - name: Customers
  - name: Sessions
paths:
  /sessions:
    get:
      tags:
        - Sessions
      summary: List sessions
      description: >-
        Returns charging sessions linked to customers. Sessions that cannot be
        associated with a customer are excluded.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sessionStationId'
        - $ref: '#/components/parameters/sessionChargerId'
        - $ref: '#/components/parameters/sessionConnectorId'
        - $ref: '#/components/parameters/sessionCustomerId'
        - $ref: '#/components/parameters/sessionAuthReference'
        - $ref: '#/components/parameters/sessionStatus'
      responses:
        '200':
          description: Session list.
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
            Link:
              $ref: '#/components/headers/SessionPaginationLink'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
        '400':
          description: >-
            Invalid filter value: stationId or chargerId not 8 alphanumeric
            characters, connectorId not a positive integer, or status not
            ACTIVE/COMPLETED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    limit:
      name: limit
      in: query
      description: >-
        Maximum number of items to return. Missing, non-integer, zero, or
        negative values use the default of 100. Values above 100 are clamped to
        100.
      schema:
        type: string
        default: '100'
    offset:
      name: offset
      in: query
      description: >-
        Zero-based index of the first item to return. Missing, non-integer, or
        negative values use 0.
      schema:
        type: string
        default: '0'
    sessionStationId:
      name: stationId
      in: query
      description: >-
        Filter sessions to a station public identifier. Must be exactly 8
        alphanumeric characters (a-zA-Z0-9); any other value returns 400.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9]{8}$
    sessionChargerId:
      name: chargerId
      in: query
      description: >-
        Filter sessions to a charger public identifier. Must be exactly 8
        alphanumeric characters (a-zA-Z0-9); any other value returns 400.
      schema:
        type: string
        pattern: ^[a-zA-Z0-9]{8}$
    sessionConnectorId:
      name: connectorId
      in: query
      description: >-
        Filter sessions to a 1-based connector number. Non-integer values and
        values below 1 return 400.
      schema:
        type: integer
        minimum: 1
    sessionCustomerId:
      name: customerId
      in: query
      description: Filter sessions to a customer identifier supplied by the partner system.
      schema:
        type: string
        minLength: 1
    sessionAuthReference:
      name: auth_reference
      in: query
      description: >-
        Filter sessions by the optional auth_reference supplied to POST
        /sessions/start.
      schema:
        type: string
        minLength: 1
    sessionStatus:
      name: status
      in: query
      description: >-
        Filter sessions by lifecycle status. Case-insensitive; any other value
        returns 400.
      schema:
        type: string
        enum:
          - ACTIVE
          - COMPLETED
  headers:
    X-Total-Count:
      description: Total number of results matching the query, regardless of limit/offset.
      schema:
        type: integer
    SessionPaginationLink:
      description: >-
        RFC 5988 pagination links. Omitted when neither a next nor previous page
        exists.
      schema:
        type: string
  schemas:
    SessionListResponse:
      type: object
      required:
        - data
        - links
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        links:
          $ref: '#/components/schemas/PaginationLinks'
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    Session:
      type: object
      required:
        - id
        - customerId
        - stationId
        - chargerId
        - connectorId
        - status
        - startTime
        - endTime
        - price
        - priceInclTax
        - energyConsumed
      properties:
        id:
          type: integer
          description: Session ID.
        customerId:
          type: string
          minLength: 1
          description: Public identifier of the customer linked to this session.
        stationId:
          type: string
          description: Public station identifier. Empty if unavailable.
        chargerId:
          type: string
          description: Public charger identifier. Empty if unavailable.
        tariffId:
          type: string
          minLength: 1
          description: >-
            Tariff identifier applied to this session. Omitted when no tariff
            applies.
        auth_reference:
          type: string
          minLength: 1
          description: >-
            Optional caller-supplied authorization reference used to correlate a
            remote-start request with the session created later by the charger.
            Omitted when none was supplied.
        connectorId:
          type: integer
          description: Connector number on the charger.
        status:
          type: string
          enum:
            - ACTIVE
            - COMPLETED
          description: ACTIVE while the session is running; COMPLETED once it has stopped.
        startTime:
          type: string
          format: date-time
          nullable: true
          description: When the session started.
        endTime:
          type: string
          format: date-time
          nullable: true
          description: When the session stopped; null while ACTIVE.
        price:
          type: number
          description: Cumulated rounded cost, excluding tax.
        priceInclTax:
          type: number
          description: Cumulated rounded cost, including tax.
        energyConsumed:
          type: number
          description: Energy delivered, in kWh.
    PaginationLinks:
      type: object
      required:
        - next
        - prev
      properties:
        next:
          type: string
          nullable: true
        prev:
          type: string
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key issued during onboarding. Every request must supply a valid
        x-api-key header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.