> ## 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.7.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. ## Error Handling Callers should send `Accept: application/json`. Errors handled by API controllers use a common JSON envelope with `message`, `request_status`, and `request_id`; validation errors may also include `errors`. The API emits 400, 401, 403, 404, 406, 410, 418, 422, 429, 500, and 503 statuses. Use the HTTP status code, not `request_status`, for control flow. The `request_id` is a best-effort support reference persisted with the API log. Request logging deliberately cannot break the request, so a logging failure can leave no matching row. Include the request timestamp when reporting an error so support can bound the lookup by date. Exceptions raised before an API controller handles the request, including unmatched routes and some middleware failures, may use Rails' `PublicExceptions` shape instead of the common envelope. `Accept: application/json` guarantees JSON for those responses; a wildcard or missing `Accept` header may receive HTML. One controller-level exception deliberately has a different body: when address validation is temporarily unavailable during session creation, HTTP 503 returns `{ "address_validation_unavailable": true }` and a `Retry-After` 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 ## Move-in / Move-out Segmentation Every session carries a `context` of `move_in` or `move_out`, set by the token that created it rather than by any request parameter. Partners running both flows are issued a separate token per context. There is no `context` query parameter. To segment, either request a single token's traffic with `token_ids[]`, or group client-side on the `context` field. Move-out sessions carry the resident's destination address, not the partner's building. Do not treat those addresses as partner properties. ## 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' context: move_in 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' context: move_out 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': $ref: '#/components/responses/403_forbidden' '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' context: type: string enum: - move_in - move_out example: move_in description: >- Traffic context for the session, set from the API token that created it. `move_in` is a resident setting up service at a home they are moving into. `move_out` is a resident leaving a partner's property. Note that the address on a move-out session is the resident's destination home, not the partner's building. Sessions created before this field was introduced read `move_in`. 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. error_envelope: type: object properties: message: $ref: '#/components/schemas/message' request_status: type: string enum: - warning - error description: >- Informational severity only; use the HTTP status code for control flow. request_id: $ref: '#/components/schemas/request_id' errors: $ref: '#/components/schemas/errors' required: - message - request_status - request_id timestamp: type: string format: date-time example: '2024-09-20T23:13:31.179Z' description: A timestamp in ISO 8601 format. request_id: type: string example: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 description: > Best-effort support reference for the request. Include the approximate request timestamp when reporting an error. A request logging failure can leave no matching API log row. errors: type: object description: >- Validation errors for session creation (e.g. missing/invalid address combination, street1, state, or zip). properties: base: type: array items: type: string example: >- Provide either (street1 and zip), (street1, city, and state), or (street1, city, and zip) street1: type: array items: type: string example: can't be blank city: type: array items: type: string example: can't be blank state: type: array items: type: string example: must be a valid state or US territory/commonwealth zip: type: array items: type: string example: must be in the form 12345 or 12345-1234 responses: 401_unauthorized: description: >- Unauthorized. Use the HTTP status code, not `request_status`, to detect the error. content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Unauthorized access request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 403_forbidden: description: >- Forbidden. The requested resource does not belong to the authenticated account, or a security policy blocked the request. content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: 'Forbidden: token_ids contain tokens not belonging to your account' request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 429_rate_limit: description: Rate Limit Exceeded headers: Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Rate limit exceeded. Please try again later. request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 500_internal_error: description: Unexpected internal error handled by an API controller. content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Internal server error request_status: error request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 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 ` Obtain tokens from your Hum representative or contact support@letshum.com. There is no self-serve API key dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.