---
title: "Get Session Status"
method: GET
path: "/sessions/{token}"
tags: ["Sessions"]
---

# Get Session Status

`GET /sessions/{token}`

Retrieves an open session. Provider results are usually returned by `POST /sessions`, but when `qualify_status` is `pending` or `retry_later`, poll `GET /sessions/{token}/services/internet` until the status resolves.

## Status Codes
- 200: Session is open
- 400: Session token is invalid
- 410: Session is closed

## Response Data
- `data.session_token`: The session token only
- `meta.session_params`: Normalized address values
- `meta.service_address`: Formatted service address
- `meta.agent_status`: Agent status values

## Important Notes
- The session token is part of the URL path for all requests after creation
- Sessions remain open until they are closed with DELETE

## Example Response
```json
{
  "message": "Session agents have successfully matched the service address. Please proceed.",
  "request_status": "ok",
  "data": {
    "session_token": "SESSION_TOKEN_PLACEHOLDER"
  },
  "meta": {
    "session_token": "SESSION_TOKEN_PLACEHOLDER",
    "session_status": "open",
    "session_params": {
      "street1": "29090 Tiffany Dr E",
      "street2": "Apt 4B",
      "city": "Southfield",
      "state": "MI",
      "zip": "48034",
      "latitude": "42.50189",
      "longitude": "-83.29528",
      "campaign_id": null
    },
    "service_address": "29090 Tiffany Dr E Apt 4B, Southfield, MI 48034-4540",
    "mdu": true,
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "created_at": "2026-07-13T12:26:15.618-04:00",
    "updated_at": "2026-07-13T12:26:15.618-04:00",
    "responded_at": "2026-07-13T16:26:16.900Z",
    "hum_data_set": "26011015"
  }
}
```

## Response `200`

Session data retrieved successfully

- object
  - `message` string, required — A message returned by the API. Includes a human-readable message about the status of the request.
  - `request_status` 'ok' | 'warning' | 'error', required — 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.
  - `qualify_status` 'available' | 'no_service' | 'pending' | 'failed' | 'retry_later' — The status of Internet service qualification for the address distinguishes a completed lookup from one that is not ready yet. **The answer is ready:** - `available`: Providers were found and are returned in `data`. - `no_service`: No providers serve this address. `data` is `[]`. You can act on this now, but Hum re-checks periodically, so re-validate it if you store it long term. **The answer is not ready, keep polling:** - `pending`: The lookup has not finished. `data` is `[]`. Retry by polling `GET /sessions/{token}/services/internet`. - `retry_later`: A transient upstream problem. `data` is `[]`. Retry by polling `GET /sessions/{token}/services/internet`. **Something went wrong:** - `failed`: The lookup errored for this address. `data` is `[]`. A `pending` lookup finishes as one of three values: `available` when providers are found, `no_service` when the lookup completes and finds none, or `failed` when it errors. `retry_later` arises separately and does not follow from `pending`. These three values should end the polling loop.
  - `data` SessionTokenData, required — Session response data. The formatted service address and normalized address components are returned in `meta`.
    - `session_token` string, required — The session token provided by the Hum API. Used to connect the response to the session in the client system.
  - `meta` Meta, required — Session metadata, including normalized input values, formatted service address, session status, and the Hum data set used for the response.
    - `session_token` string, required — The session token provided by the Hum API. Used to connect the response to the session in the client system.
    - `session_status` 'open' | 'closed', required — The status of the session.
    - `agent_status` AgentStatus, required
      - `geocoding` 'pending' | 'matched' | 'multiple' | 'failed' — 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` 'pending' | 'matched' | 'failed' — 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` 'pending' — The status of the checkout agent. Pending: The agent has not yet begun processing a checkout for service.
    - `session_params` NormalizedSessionParams, required — Address and campaign values after normalization. Coordinate values are serialized as strings in response metadata.
      - `street1` string, required
      - `street2` string, nullable, required
      - `city` string, required
      - `state` string, required
      - `zip` string, required
      - `latitude` string, nullable, required
      - `longitude` string, nullable, required
      - `campaign_id` string, nullable, required
    - `service_address` string, required — The complete service address as a single string.
    - `mdu` boolean, required — Whether the normalized service address is a multi-dwelling unit.
    - `created_at` string, date-time, required — The timestamp when the session was created.
    - `updated_at` string, date-time, required — The timestamp when the session was last updated.
    - `responded_at` string, date-time, required — The timestamp when the response was generated.
    - `hum_data_set` string, required — The version of the Hum data set used to generate the response. This version may change as the data set is updated.

## Other responses

- `400` — Bad request. This includes an invalid session token. Use the HTTP status code, not `request_status`, to detect the error.
- `401` — Unauthorized. Use the HTTP status code, not `request_status`, to detect the error.
- `410` — The session has been closed. Use the HTTP status code, not `request_status`, to detect the error.
- `415` — The request was rejected because its content type is unsupported.
- `422` — Session validation failed. Use the HTTP status code, not `request_status`, to detect the error.
- `429` — Rate Limit Exceeded
- `500` — Unexpected internal error handled by an API controller.

---

[API](https://skmtc.dev/letshum/apis/hum-api.md) · [All operations](https://skmtc.dev/letshum/apis/hum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/letshum/hum-api/revisions/5e36540cb9b0/schema)