spicrawlspicrawlDocs
Sessions

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.

Requires scope: sessions

GET
/v1/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.

Authorization

bearerAuth
AuthorizationBearer <token>

Authorization: Bearer <key>. Read the key from the SPICRAWL_API_KEY environment variable; never hard-code or log it. spicrawl_test_… keys can never spend live credits. Scopes: scrape, batch, sessions (granted by default), browser and read (granted deliberately). A missing scope is 403 ERR::AUTH::INSUFFICIENT_SCOPE naming the scope.

In: header

Query Parameters

limit?integer

Page size. Out-of-range or non-integer values are refused with 400, not clamped.

Range1 <= value <= 200
Default50
engine?string

Only sessions pinned to this engine. Case-insensitive.

Value in

  • "fetch"
  • "obscura"
  • "chromium"
  • "camoufox"
status?string

Only sessions whose clock-derived status matches. Case-insensitive. Filtered after the read; see the operation description.

Value in

  • "active"
  • "released"
  • "expired"
cursor?string

The next_cursor from the previous page, passed back verbatim. A value this API did not issue is refused with 400.

Match^[0-9]+\.[0-9A-Za-z-]+$

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/v1/sessions"
{  "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"}

Stop an open job accepting items POST

Sets `open` to false so the job completes once its queued work drains; takes no body.

Create a persisted browser session POST

Creates a session: a sealed cookie jar and web-storage snapshot, pinned to one engine and one exit intent, that you reuse by passing its `id` as `session_id` on `/v1/scrape`.