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

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

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

## GET /v1/sessions

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

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

### Example

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer; default `50` | no | Page size. Out-of-range or non-integer values are refused with 400, not clamped. |
| `engine` | query | string: `fetch`, `obscura`, `chromium`, `camoufox` | no | Only sessions pinned to this engine. Case-insensitive. |
| `status` | query | string: `active`, `released`, `expired` | no | Only sessions whose clock-derived status matches. Case-insensitive. Filtered after the read; see the operation description. |
| `cursor` | query | string | no | The `next_cursor` from the previous page, passed back verbatim. A value this API did not issue is refused with 400. |

### Responses

#### 200

One page of sessions.

`application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `sessions` | array of object (`Session`) | yes | Sessions on this page, newest first. May be shorter than `limit` (or empty) when a `status` filter is applied. |
| `next_cursor` | string | no | Pass as `cursor` to get the next page. Absent when the last unfiltered page was short, which means there are no more sessions. |

Example `page`

```json
{
  "sessions": [
    {
      "id": "01J9ZQ4M7R3T8VX2K5N6P0B1CD",
      "project_id": "01J9Y0000000000000000PROJ1",
      "engine": "chromium",
      "status": "active",
      "sticky_key": "acct-4812",
      "proxy": {
        "tier": "residential",
        "country": "de"
      },
      "created_at": "2026-09-22T10:00:00Z",
      "last_used_at": "2026-09-22T10:05:12Z",
      "expires_at": "2026-09-22T12:05:12Z",
      "hard_expires_at": "2026-09-29T10:00:00Z",
      "usage_count": 3,
      "context": {
        "schema_version": 1,
        "cookies": 14,
        "origins": 2,
        "bytes": 5821
      },
      "lease": {
        "holder": "render-7",
        "expires_at": "2026-09-22T10:06:00Z"
      }
    }
  ],
  "next_cursor": "1790000000000000000.01J9ZQ4M7R3T8VX2K5N6P0B1CD"
}
```

#### 400

The request is invalid. Not retryable; fix the request using `code` and `diagnostics.hint`.

Headers: `X-Request-Id`.

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

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

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