# Get one session's metadata

> Returns the session's metadata and a non-secret context summary.

Source: https://docs.spicrawl.com/api-reference/sessions/sessions-get

## GET /v1/sessions/{sessionID}

Operation ID: `sessionsGet`. API key scope: `sessions`.

Returns the session's metadata and a non-secret context summary. Never returns cookies, and does not
slide the TTL, so it is safe to poll. Released and expired sessions are still returned (200) with
their `status`; only a deleted or unknown session is 404. A malformed id also answers 404
`ERR::SESSION::NOT_FOUND`.

### Example

```bash
curl "https://api.spicrawl.com/v1/sessions/{sessionID}" \
  -H "Authorization: Bearer $SPICRAWL_API_KEY"
```

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `sessionID` | path | string | yes | Session id from `POST /v1/sessions` (26-character ULID; a UUID is also accepted). A malformed id answers 404 `ERR::SESSION::NOT_FOUND`, the same as an unknown one. |

### Responses

#### 200

The session.

`application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Session id (26-character ULID). Pass it as `session_id` on `/v1/scrape`. |
| `project_id` | string | yes | Project the session belongs to (the creating key's project). |
| `engine` | string: `fetch`, `obscura`, `chromium`, `camoufox` | yes | Engine a session is pinned to for its whole life. Scrapes on the session run on this engine; `fingerprint` is only valid with `camoufox`. |
| `status` | string: `active`, `released`, `expired` | yes | Derived from the clock, not a stored flag. `active` sessions can be used; `released` and `expired` ones have no context and cannot be revived. Create a new session. |
| `sticky_key` | string | yes | Exit pin in use. The lowercase session id when you did not set one; empty string when `rotate_ip` was set. |
| `proxy` | object (`SessionProxy`) | yes | The session's exit intent. Not an endpoint or IP. |
| `created_at` | string (date-time) | yes | Creation time, RFC 3339 UTC. |
| `last_used_at` | string \| null (date-time) | yes | Last time a successful scrape used the session. Null means never used. |
| `expires_at` | string (date-time) | yes | Current expiry. Each successful scrape moves it to that time + the session's `ttl_seconds` (never earlier than it was, never past `hard_expires_at`). After it passes the context is purged. |
| `hard_expires_at` | string (date-time) | no | Fixed ceiling set at creation from the organization's maximum TTL. Plan a re-login before this time. Omitted only for legacy rows. |
| `released_at` | string (date-time) | no | When the session was released. Present only on released sessions. |
| `usage_count` | integer | yes | Number of successful scrapes that have used the session. Failed scrapes and `/context` reads do not count. |
| `context` |  | yes | Size summary of the stored context. Null once the session is not active (the context has been purged). |
| `retired` | string: `expired`, `usage_exhausted`, `explicit` | no | Why a worker took this session out of service. Absent while usable. A retired session should be replaced. |
| `domain_scores` | object | no | Per-domain block evidence the workers maintain. Omitted when empty. |
| `fingerprint` | object | no | Camoufox fingerprint, as stored. Omitted when none was set. |
| `lease` | object (`SessionLease`) | no | Present only while a render holds the single-writer lease. While present, other scrapes, release and delete get 409 `ERR::SESSION::BUSY`. |
| `warnings` | array of string | no | Decisions made on your behalf at creation, e.g. a TTL reduced to the organization maximum. Only on the create response; omitted when empty. |

#### 401

Missing, invalid, revoked or expired key. Not retryable with the same key.

Headers: `X-Request-Id`.

`application/problem+json` (`Problem` schema).

#### 403

The key lacks the scope this route requires (`ERR::AUTH::INSUFFICIENT_SCOPE`), or the action is not permitted.

Headers: `X-Request-Id`.

`application/problem+json` (`Problem` schema).

#### 404

No such resource for this key's organization.

Headers: `X-Request-Id`.

`application/problem+json` (`Problem` schema).

#### 500

Internal error. Retryable when `retryable` is true.

Headers: `X-Request-Id`.

`application/problem+json` (`Problem` schema).

Full OpenAPI spec: https://docs.spicrawl.com/openapi.yaml