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

# List Sessions

> Returns a paginated list of sessions with address, cart progression, order, and commission data.
Scoped to all tokens belonging to the authenticated client.

## Filtering
- `start_date` / `end_date`: ISO 8601 date strings to bound the query window
- `updated_since`: Return only sessions whose session or order data changed on or after this time; results are ordered by most recent change first
- `token_ids[]`: Restrict to specific API tokens (must belong to your account)
- `with_clicks`: When `true`, only returns sessions with click activity

## Pagination
Results are paginated at 50 sessions per page. Use the `page` parameter and
the `meta.pages` field to navigate.

## Syncing order status
To keep a local copy of order status current, poll with `updated_since` set to the time of
your last successful sync and page through all results. A session is returned whenever the
session or its order changed — including installs, cancellations, and commission updates on
sessions created long ago. Treat each returned row as authoritative and overwrite your stored
copy. Do not use `start_date` as a sync cursor: it filters on session creation time, so status
changes on previously synced sessions are never returned. Unrecognized parameters are ignored.




## OpenAPI

````yaml /swagger.yaml get /analytics/sessions
openapi: 3.0.1
info:
  title: Hum API
  version: 1.6.0
  description: >
    The Hum API provides a comprehensive solution for discovering and comparing
    Internet service providers (ISPs) at specific addresses. 

    By leveraging AI-powered agents, the API normalizes addresses, identifies
    available providers, and returns detailed information 

    about service plans, pricing, and technology options. This makes it an ideal
    solution for businesses and applications that need 

    to help users find and compare Internet service options in their area.


    The API provides endpoints for creating and managing sessions, as well as
    verifying the connection to the API. Each session represents a service
    address lookup and its provider results.


    ## API Versioning

    This API uses semantic versioning. The current version is v1.6.0. For
    breaking changes, the major version will be incremented.


    ## Rate Limiting

    API requests are protected by a global limit of 100 requests per second per
    client IP. Analytics endpoints have an additional limit of 60 requests per
    minute per client IP. When a limit is exceeded, the API returns HTTP 429
    with a `Retry-After: 60` header. No other rate-limit headers are sent.


    ## Authentication

    All endpoints require Bearer token authentication. Tokens must be included
    in the Authorization header.
  termsOfService: https://www.letshum.com/terms-of-service
  contact:
    name: Hum API Support
    url: https://docs.letshum.com
    email: support@letshum.com
  license:
    name: Proprietary
    url: https://www.letshum.com/terms-of-service
servers:
  - url: https://api-sandbox.letshum.com
    description: Sandbox environment
  - url: https://api.letshum.com
    description: Production environment
security: []
paths:
  /analytics/sessions:
    summary: Partner Analytics - Sessions
    description: >
      Paginated list of sessions with order and cart progression data,

      scoped to the authenticated token's client.


      ## Data Scoping

      - Results are scoped to all tokens belonging to the authenticated client

      - Only sessions with human activity are returned

      - Optional `token_ids[]` filter must reference tokens owned by the
      authenticated client


      ## Rate Limiting

      Analytics endpoints are limited to 60 requests per minute per IP.
    get:
      tags:
        - Analytics
      summary: List Sessions
      description: >
        Returns a paginated list of sessions with address, cart progression,
        order, and commission data.

        Scoped to all tokens belonging to the authenticated client.


        ## Filtering

        - `start_date` / `end_date`: ISO 8601 date strings to bound the query
        window

        - `updated_since`: Return only sessions whose session or order data
        changed on or after this time; results are ordered by most recent change
        first

        - `token_ids[]`: Restrict to specific API tokens (must belong to your
        account)

        - `with_clicks`: When `true`, only returns sessions with click activity


        ## Pagination

        Results are paginated at 50 sessions per page. Use the `page` parameter
        and

        the `meta.pages` field to navigate.


        ## Syncing order status

        To keep a local copy of order status current, poll with `updated_since`
        set to the time of

        your last successful sync and page through all results. A session is
        returned whenever the

        session or its order changed — including installs, cancellations, and
        commission updates on

        sessions created long ago. Treat each returned row as authoritative and
        overwrite your stored

        copy. Do not use `start_date` as a sync cursor: it filters on session
        creation time, so status

        changes on previously synced sessions are never returned. Unrecognized
        parameters are ignored.
      operationId: listAnalyticsSessions
      parameters:
        - name: page
          in: query
          description: Page number (default 1, 50 results per page)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: start_date
          in: query
          description: Filter sessions created on or after this date (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            example: '2026-01-01T00:00:00Z'
        - name: end_date
          in: query
          description: Filter sessions created on or before this date (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            example: '2026-03-31T23:59:59Z'
        - name: updated_since
          in: query
          description: >
            Return only sessions whose session or order data changed on or after
            this time

            (ISO 8601). When provided, results are ordered by most recent change
            first.

            Invalid datetime values are ignored.
          required: false
          schema:
            type: string
            format: date-time
            example: '2026-03-10T00:00:00Z'
        - name: token_ids[]
          in: query
          description: |
            Filter to sessions from specific API tokens. All provided token IDs
            must belong to the authenticated client or a 403 is returned.
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: with_clicks
          in: query
          description: When true, only return sessions that have click activity
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Paginated list of analytics sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/message'
                  request_status:
                    $ref: '#/components/schemas/request_status'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/analytics_session_summary'
                  meta:
                    $ref: '#/components/schemas/analytics_pagination_meta'
                required:
                  - message
                  - request_status
                  - data
                  - meta
              examples:
                with_results:
                  summary: Sessions with order data
                  value:
                    message: Analytics sessions
                    request_status: ok
                    data:
                      - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        created_at: '2026-03-01T12:00:00Z'
                        campaign_id: spring_promo_2026
                        address:
                          street1: 123 Main St
                          street2: Apt 4B
                          city: Detroit
                          state: MI
                          zip: '48201'
                        furthest_step: 6
                        order_number: HUM-A1B2C3D4
                        status: complete
                        ordered_at: '2026-03-01T12:30:00Z'
                        installed: true
                        installed_at: '2026-03-05T14:00:00Z'
                        commission_cents: 5000
                      - id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                        created_at: '2026-03-01T11:00:00Z'
                        campaign_id: null
                        address:
                          street1: 456 Oak Ave
                          street2: null
                          city: Ann Arbor
                          state: MI
                          zip: '48104'
                        furthest_step: 3
                        order_number: null
                        status: null
                        ordered_at: null
                        installed: null
                        installed_at: null
                        commission_cents: null
                    meta:
                      responded_at: '2026-03-12T15:00:00Z'
                      page: 1
                      pages: 5
                      count: 237
                empty_results:
                  summary: No sessions found
                  value:
                    message: Analytics sessions
                    request_status: ok
                    data: []
                    meta:
                      responded_at: '2026-03-12T15:00:00Z'
                      page: 1
                      pages: 0
                      count: 0
        '401':
          $ref: '#/components/responses/401_unauthorized'
        '403':
          description: Forbidden — token_ids contain tokens not belonging to your account
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      Forbidden: token_ids contain tokens not belonging to your
                      account
                  request_status:
                    type: string
                    example: error
        '429':
          $ref: '#/components/responses/429_rate_limit'
        '500':
          $ref: '#/components/responses/500_internal_error'
      security:
        - bearerAuth: []
components:
  schemas:
    message:
      type: string
      example: What happened in the most recent request.
      description: >-
        A message returned by the API.  Includes a human-readable message about
        the status of the request.
    request_status:
      type: string
      enum:
        - ok
        - warning
        - error
      example: ok
      description: >
        An informational summary returned in API response bodies: `ok` for
        successful responses, `warning` for standard request errors, and `error`
        for endpoint-specific failures. Integrations must use the HTTP status
        code, not `request_status`, to determine whether a request succeeded.
    analytics_session_summary:
      type: object
      description: Session summary returned in the list endpoint.
      properties:
        id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        created_at:
          type: string
          format: date-time
          example: '2026-03-01T12:00:00Z'
        campaign_id:
          type: string
          nullable: true
          example: spring_promo_2026
          description: >-
            Campaign tracking identifier, if provided when the session was
            created.
        address:
          $ref: '#/components/schemas/analytics_address'
        furthest_step:
          type: integer
          nullable: true
          minimum: 1
          maximum: 8
          example: 6
          description: >-
            Highest checkout step reached during this session (1-8). Null if no
            cart events.
        order_number:
          type: string
          nullable: true
          example: HUM-A1B2C3D4
          description: Order number, if an order was placed.
        status:
          type: string
          nullable: true
          enum:
            - draft
            - submitted
            - processing
            - confirmed
            - complete
            - cancelled
          example: complete
          description: >-
            Order status. Null if no order was placed. Cancelled orders are
            final.
        ordered_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-03-01T12:30:00Z'
          description: When the order was submitted.
        installed:
          type: boolean
          nullable: true
          example: true
          description: >-
            Whether the service has been installed. Always false for cancelled
            orders.
        installed_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-03-05T14:00:00Z'
          description: When the service was installed. Null for cancelled orders.
        commission_cents:
          type: integer
          nullable: true
          example: 5000
          description: >-
            Locked commission in cents. Null if no commission recorded and for
            cancelled orders.
    analytics_pagination_meta:
      type: object
      description: Pagination metadata for list responses.
      properties:
        responded_at:
          $ref: '#/components/schemas/responded_at'
        page:
          type: integer
          example: 1
          description: Current page number.
        pages:
          type: integer
          example: 5
          description: Total number of pages.
        count:
          type: integer
          example: 237
          description: Total number of sessions matching the query.
    analytics_address:
      type: object
      description: Service address for the session.
      properties:
        street1:
          type: string
          nullable: true
          example: 123 Main St
        street2:
          type: string
          nullable: true
          example: Apt 4B
        city:
          type: string
          nullable: true
          example: Detroit
        state:
          type: string
          nullable: true
          example: MI
        zip:
          type: string
          nullable: true
          example: '48201'
    responded_at:
      allOf:
        - $ref: '#/components/schemas/timestamp'
        - description: The timestamp when the response was generated.
    timestamp:
      type: string
      format: date-time
      example: '2024-09-20T23:13:31.179Z'
      description: A timestamp in ISO 8601 format.
  responses:
    401_unauthorized:
      description: >-
        Unauthorized. Use the HTTP status code, not `request_status`, to detect
        the error.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized access
              request_status:
                type: string
                enum:
                  - warning
                example: warning
            required:
              - message
              - request_status
    429_rate_limit:
      description: Rate Limit Exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Too many requests
              message:
                type: string
                example: Rate limit exceeded. Please try again later.
              status:
                type: integer
                enum:
                  - 429
                example: 429
            required:
              - error
              - message
              - status
    500_internal_error:
      description: >-
        Internal Server Error. The response body is not guaranteed to use the
        standard API envelope.
      content:
        application/json:
          schema:
            oneOf:
              - type: object
                properties:
                  status:
                    type: integer
                    example: 500
                  error:
                    type: string
                    example: Internal Server Error
                required:
                  - status
                  - error
              - type: object
                properties:
                  message:
                    type: string
                    example: Internal server error
                required:
                  - message
  headers:
    Retry-After:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
      example: 60
      required: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Bearer token authentication using API tokens.

        Include the token in the Authorization header as: `Authorization: Bearer
        <token>`


        Obtain tokens from your Hum representative or contact
        support@letshum.com. There is no self-serve API key dashboard.

````