---
title: "List the key's project's sessions, newest first"
method: GET
path: "/v1/sessions"
tags: ["Sessions"]
---

# List the key's project's sessions, newest first

`GET /v1/sessions`

## Request

- Base URL: `https://api.spicrawl.com`
- URL: `https://api.spicrawl.com/v1/sessions`
- Auth: HTTP bearer

Lists sessions in the API key's project (not the whole organization), ordered by `created_at` then
`id`, descending. Never returns cookies.

Pitfalls:
- The `status` filter is applied after the page is read, because status is derived from the clock.
  A page can therefore hold fewer than `limit` items, or none, and still carry `next_cursor`.
  Keep paging until `next_cursor` is absent.
- `next_cursor` appears only when the unfiltered page was full. Pass it back verbatim as `cursor`.

## Query parameters

- `limit` integer
- `engine` 'fetch' | 'js' | 'browser'
- `status` 'active' | 'released' | 'expired'
- `cursor` string

## Response `200`

One page of sessions.

- SessionList
  - `sessions` Session[], required: Sessions on this page, newest first. May be shorter than `limit` (or empty) when a `status` filter is applied.
    - `id` string, required: Session id (26-character ULID). Pass it as `session_id` on `/v1/scrape`.
    - `project_id` string, required: Project the session belongs to (the creating key's project).
    - `engine` 'fetch' | 'js' | 'browser': The rendering tier a session is bound to for its lifetime (`fetch` is HTTP only, `js` is JavaScript rendering, `browser` is full-browser rendering). Chosen automatically when the session is created unless the create names one.
    - `status` 'active' | 'released' | 'expired', required: 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, required: Exit pin in use. The lowercase session id when you did not set one; empty string when `rotate_ip` was set.
    - `proxy` SessionProxy, required: The session's exit intent. Not an endpoint or IP.
      - `tier` 'none' | 'datacenter' | 'residential', required: Exit tier. `residential` when created with `premium_proxy`, otherwise `datacenter`. `none` is reserved and not produced by the create endpoint.
      - `country` string: Lowercase alpha-2 exit country. Omitted when no country was requested.
      - `region_pool` string: Regional pool requested at creation. Omitted when none.
    - `created_at` string, date-time, required: Creation time, RFC 3339 UTC.
    - `last_used_at` string, date-time, nullable, required: Last time a successful scrape used the session. Null means never used.
    - `expires_at` string, date-time, required: 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: 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: When the session was released. Present only on released sessions.
    - `usage_count` integer, required: Number of successful scrapes that have used the session. Failed scrapes and `/context` reads do not count.
    - `context` SessionContextSummary, required: Non-secret counts describing the stored context.
      - `schema_version` integer, required: Stored context format version. Currently 1.
      - `cookies` integer, required: Number of cookies stored.
      - `origins` integer, required: Distinct origins across local storage, session storage and IndexedDB.
      - `bytes` integer, required: Serialised plaintext size in bytes. The limit is 1048576.
    - `retired` 'expired' | 'usage_exhausted' | 'explicit': Why a worker took this session out of service. Absent while usable. A retired session should be replaced.
    - `domain_scores` object: Per-domain block evidence the workers maintain. Omitted when empty.
    - `fingerprint` object: Browser fingerprint, as stored. Omitted when none was set.
    - `lease` SessionLease: Present only while a render holds the single-writer lease. While present, other scrapes, release and delete get 409 `ERR::SESSION::BUSY`.
      - `holder` string: Identifier of the worker holding the lease. Diagnostic only.
      - `expires_at` string, date-time, required: When the lease lapses at the latest. Retry after this time.
    - `warnings` string[]: Decisions made on your behalf at creation, e.g. a TTL reduced to the organization maximum. Only on the create response; omitted when empty.
  - `next_cursor` string: Pass as `cursor` to get the next page. Absent when the last unfiltered page was short, which means there are no more sessions.

## Other responses

- `400`: The request is invalid. Not retryable; fix the request using `code` and `diagnostics.hint`.
- `401`: Missing, invalid, revoked or expired key. Not retryable with the same key.
- `403`: The key lacks the scope this route requires (`ERR::AUTH::INSUFFICIENT_SCOPE`), or the action is not permitted.
- `500`: Internal error. Retryable when `retryable` is true.

---

[API](https://skmtc.dev/spicrawl/apis/spicrawl-api.md) · [All operations](https://skmtc.dev/spicrawl/apis/spicrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spicrawl/apis/spicrawl-api/revisions/c4b4c6f97219?raw)