> ## 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.

# Get Session Status

> Retrieves the current status of a session, including normalized address data and processing status of various 
Hum AI agents.

## Polling Guidelines
- Initial request: Immediately after session creation
- Subsequent requests: Every 2-3 seconds until agents complete
- Maximum polling duration: 30 seconds
- Implement exponential backoff if status doesn't change

## Status Codes
- 200: Session active and data available
- 202: Session active but still processing
- 410: Session expired or closed

## Response Data
- Normalized address
- Geocoding results
- Agent processing status
- Available services (when ready)

## Important Notes
- The session token is part of the URL path for all requests after creation
- The session token is required for all subsequent requests
- The session token is valid for 30 minutes of inactivity
- Rate limits apply to all requests

## Example Response
```json
{
  "message": "Session data retrieved successfully",
  "request_status": "ok",
  "data": {
    "service_address": "29090 TIFFANY DR E, SOUTHFIELD, MI 48034",
  },
  "meta": {
    "agent_status": {
      "geocoding": "matched",
      "internet": "pending"
    }
  }
}
```




## OpenAPI

````yaml swagger.yaml get /sessions/{token}
openapi: 3.0.1
info:
  title: Hum API
  version: 1.5.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, with AI agents and workers running in
    the background to gather and validate provider information.


    ## API Versioning

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


    ## Rate Limiting

    All endpoints are subject to rate limiting. Limits are returned in response
    headers:

    - `X-RateLimit-Limit`: Maximum requests per time window

    - `X-RateLimit-Remaining`: Remaining requests in current window  

    - `X-RateLimit-Reset`: Time when current window resets


    ## Authentication

    All endpoints except /ping 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:
  /sessions/{token}:
    parameters:
      - name: token
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/session_token'
        description: The session token identifying the specific session
    get:
      tags:
        - Sessions
      summary: Get Session Status
      description: >
        Retrieves the current status of a session, including normalized address
        data and processing status of various 

        Hum AI agents.


        ## Polling Guidelines

        - Initial request: Immediately after session creation

        - Subsequent requests: Every 2-3 seconds until agents complete

        - Maximum polling duration: 30 seconds

        - Implement exponential backoff if status doesn't change


        ## Status Codes

        - 200: Session active and data available

        - 202: Session active but still processing

        - 410: Session expired or closed


        ## Response Data

        - Normalized address

        - Geocoding results

        - Agent processing status

        - Available services (when ready)


        ## Important Notes

        - The session token is part of the URL path for all requests after
        creation

        - The session token is required for all subsequent requests

        - The session token is valid for 30 minutes of inactivity

        - Rate limits apply to all requests


        ## Example Response

        ```json

        {
          "message": "Session data retrieved successfully",
          "request_status": "ok",
          "data": {
            "service_address": "29090 TIFFANY DR E, SOUTHFIELD, MI 48034",
          },
          "meta": {
            "agent_status": {
              "geocoding": "matched",
              "internet": "pending"
            }
          }
        }

        ```
      operationId: getSession
      responses:
        '200':
          description: Session data retrieved successfully
          headers:
            session_token:
              $ref: '#/components/headers/session_token'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/message'
                  request_status:
                    $ref: '#/components/schemas/request_status'
                  data:
                    type: object
                    properties:
                      service_address:
                        $ref: '#/components/schemas/service_address'
                    required:
                      - service_address
                  meta:
                    $ref: '#/components/schemas/meta'
                required:
                  - message
                  - request_status
                  - data
                  - meta
        '202':
          description: >-
            Session has been created, but the Hum agents have not yet completed
            their initial processing.
          headers:
            session_token:
              $ref: '#/components/headers/session_token'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/message'
                  request_status:
                    $ref: '#/components/schemas/request_status'
                  data:
                    type: object
                    properties:
                      service_address:
                        $ref: '#/components/schemas/service_address'
                    required:
                      - service_address
                  meta:
                    $ref: '#/components/schemas/meta'
                required:
                  - message
                  - request_status
                  - data
                  - meta
        '400':
          $ref: '#/components/responses/400_bad_request'
        '401':
          $ref: '#/components/responses/401_unauthorized'
        '404':
          $ref: '#/components/responses/404_not_found'
        '406':
          $ref: '#/components/responses/406_not_acceptable'
        '410':
          $ref: '#/components/responses/410_gone'
        '422':
          $ref: '#/components/responses/422_unprocessable'
        '429':
          $ref: '#/components/responses/429_rate_limit'
        '500':
          $ref: '#/components/responses/500_internal_error'
      security:
        - bearerAuth: []
components:
  schemas:
    session_token:
      type: string
      example: XqCmeTVgYXrbWrZFZEymkD
      description: >-
        The session token provided by the Hum API. Used to connect the response
        to the session in the client system.
    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: |
        A status code summarizing the outcome of this response.
        - ok: Request was successful
        - warning: Request was processed but with some issues
        - error: Request failed
    service_address:
      type: string
      example: 1420 Washington Blvd, Detroit, MI 48201
      description: The complete service address as a single string.
    meta:
      type: object
      properties:
        session_token:
          $ref: '#/components/schemas/session_token'
        session_status:
          allOf:
            - $ref: '#/components/schemas/session_status'
          nullable: true
        agent_status:
          allOf:
            - $ref: '#/components/schemas/agent_status'
          nullable: true
        session_params:
          allOf:
            - $ref: '#/components/schemas/session_params'
          nullable: true
        service_address:
          allOf:
            - $ref: '#/components/schemas/service_address'
          nullable: true
        created_at:
          allOf:
            - $ref: '#/components/schemas/created_at'
          nullable: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/updated_at'
          nullable: true
        responded_at:
          $ref: '#/components/schemas/responded_at'
        hum_data_set:
          $ref: '#/components/schemas/hum_data_set'
      required:
        - session_token
        - session_status
        - responded_at
        - hum_data_set
      description: >-
        Metadata about the session. Can be used to track the status of the
        session, time since creation, and time since last update.
    session_status:
      type: string
      enum:
        - open
        - closed
      example: open
      description: The status of the session.
    agent_status:
      type: object
      properties:
        geocoding:
          type: string
          enum:
            - pending
            - matched
            - multiple
            - failed
          example: matched
          description: >-
            The status of the geocoding agent.  Pending: The agent has not yet
            processed the address. Matched: The agent has found a single match
            for the address. Multiple: The agent has found multiple matches for
            the address. Failed: The agent was unable to match the address.
        internet:
          type: string
          enum:
            - pending
            - matched
            - failed
          example: matched
          description: >-
            The status of the Internet service availability agent. Pending: The
            agent has not yet processed the address. Matched: The agent has
            found Internet service providers for the address. Failed: The agent
            was unable to find Internet service providers for the address.
        checkout:
          type: string
          enum:
            - pending
          example: pending
          description: >-
            The status of the checkout agent. Pending: The agent has not yet
            begun processing a checkout for service. 
    session_params:
      type: object
      description: >
        Service address. Provide one of: **street1** and **zip**; **street1**,
        **city**, and **state**; or **street1**, **city**, and **zip**. State is
        optional when zip is present.
      properties:
        street1:
          $ref: '#/components/schemas/street1'
        street2:
          $ref: '#/components/schemas/street2'
        city:
          $ref: '#/components/schemas/city'
        state:
          $ref: '#/components/schemas/state'
        zip:
          $ref: '#/components/schemas/zip'
        latitude:
          $ref: '#/components/schemas/latitude'
        longitude:
          $ref: '#/components/schemas/longitude'
        campaign_id:
          $ref: '#/components/schemas/campaign_id'
      required:
        - street1
    created_at:
      allOf:
        - $ref: '#/components/schemas/timestamp'
        - description: The timestamp when the session was created.
    updated_at:
      allOf:
        - $ref: '#/components/schemas/timestamp'
        - description: The timestamp when the session was last updated.
    responded_at:
      allOf:
        - $ref: '#/components/schemas/timestamp'
        - description: The timestamp when the response was generated.
    hum_data_set:
      type: string
      pattern: ^\d+$
      example: '25041808'
      description: >-
        The version of the Hum data set used to generate the response. This
        version may change as the data set is updated.
    response_meta:
      type: object
      properties:
        responded_at:
          $ref: '#/components/schemas/responded_at'
        hum_data_set:
          $ref: '#/components/schemas/hum_data_set'
    errors:
      type: object
      description: >-
        Validation errors for session creation (e.g. missing/invalid address
        combination, street1, state, or zip).
      properties:
        errors:
          type: object
          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
    street1:
      type: string
      minLength: 1
      maxLength: 100
      example: 29090 Tiffany Drive E
      description: The street address of the service location.
    street2:
      type: string
      minLength: 1
      maxLength: 50
      example: A2
      description: The unit, apartment, or suite number of the service location.
    city:
      type: string
      minLength: 1
      maxLength: 50
      example: Southfield
      description: >-
        The city of the service location. Required when using the (street1,
        city, state) combination; optional when providing street1 and zip.
    state:
      type: string
      pattern: ^[A-Z]{2}$
      enum:
        - AL
        - AK
        - AZ
        - AR
        - CA
        - CO
        - CT
        - DE
        - FL
        - GA
        - HI
        - ID
        - IL
        - IN
        - IA
        - KS
        - KY
        - LA
        - ME
        - MD
        - MA
        - MI
        - MN
        - MS
        - MO
        - MT
        - NE
        - NV
        - NH
        - NJ
        - NM
        - NY
        - NC
        - ND
        - OH
        - OK
        - OR
        - PA
        - PR
        - RI
        - SC
        - SD
        - TN
        - TX
        - UT
        - VT
        - VA
        - WA
        - WV
        - WI
        - WY
      example: MI
      description: >-
        The two-letter state abbreviation. Required when using the (street1,
        city, state) combination; optional when providing street1 and zip.
    zip:
      type: string
      pattern: ^\d{5}(-\d{4})?$
      example: 48034
      description: >-
        The ZIP code in 12345 or 12345-6789 format. Required when using the
        (street1, zip) combination; optional when providing street1, city, and
        state.
    latitude:
      type: number
      format: float
      example: 42.501721339274
      description: The latitude of the service address.
    longitude:
      type: number
      format: float
      example: -83.286263465881
      description: The longitude of the service address.
    campaign_id:
      type: string
      minLength: 1
      maxLength: 100
      example: 1iYyMxsnTy87tFOvukTi7V
      description: >-
        A unique identifier for the campaign. This is used to track the source
        of the session in your internal system.
    timestamp:
      type: string
      format: date-time
      example: '2024-09-20T23:13:31.179Z'
      description: A timestamp in ISO 8601 format.
  headers:
    session_token:
      description: >-
        The session token provided by the Hum API. Used to connect the response
        to the session in the client system.
      required: true
      schema:
        type: string
      example: XqCmeTVgYXrbWrZFZEymkD
    X-RateLimit-Limit:
      description: The maximum number of requests allowed per time window
      schema:
        type: integer
      example: 100
      required: true
    X-RateLimit-Remaining:
      description: The number of requests remaining in the current time window
      schema:
        type: integer
      example: 99
      required: true
    X-RateLimit-Reset:
      description: >-
        The time at which the current rate limit window resets in UTC epoch
        seconds
      schema:
        type: integer
      example: 1612137072
      required: true
  responses:
    400_bad_request:
      description: Bad Request
      headers:
        session_token:
          $ref: '#/components/headers/session_token'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Missing session token
              request_status:
                $ref: '#/components/schemas/request_status'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - meta
    401_unauthorized:
      description: Unauthorized
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: You are not authorized to access this resource.
              request_status:
                $ref: '#/components/schemas/request_status'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - meta
    404_not_found:
      description: Session not found
      headers:
        session_token:
          $ref: '#/components/headers/session_token'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Session not found
              request_status:
                $ref: '#/components/schemas/request_status'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - meta
    406_not_acceptable:
      description: Content type must be 'application/json'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: >-
                  The content type 'foo/bar' is not supported. Please ensure
                  that your content type is 'application/json' and try again.
              request_status:
                $ref: '#/components/schemas/request_status'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - meta
    410_gone:
      description: The session has been closed
      headers:
        session_token:
          $ref: '#/components/headers/session_token'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: The requested resource is no longer available.
              request_status:
                $ref: '#/components/schemas/request_status'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - meta
    422_unprocessable:
      description: Incorrect parameters or other validation error
      headers:
        session_token:
          $ref: '#/components/headers/session_token'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/message'
              request_status:
                $ref: '#/components/schemas/request_status'
              errors:
                $ref: '#/components/schemas/errors'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - errors
              - meta
    429_rate_limit:
      description: Rate Limit Exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Too many requests. Please try again later.
              request_status:
                $ref: '#/components/schemas/request_status'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - meta
    500_internal_error:
      description: Internal Server Error
      headers:
        session_token:
          $ref: '#/components/headers/session_token'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Internal server error
              request_status:
                $ref: '#/components/schemas/request_status'
              meta:
                $ref: '#/components/schemas/response_meta'
            required:
              - message
              - request_status
              - meta
  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 through your Hum API account dashboard or contact
        support@letshum.com for access.

````