spicrawlspicrawlDocs
Sessions

End a session and purge its context

Marks the session `released` and deletes its stored cookies and storage in the same transaction.

Requires scope: sessions

POST
/v1/sessions/{sessionID}/release

Marks the session released and deletes its stored cookies and storage in the same transaction. The browser worker's own copy of the session state in object storage is deleted too. The session row stays readable via GET /v1/sessions/{id}; the context does not. This is not "release the lease, keep the state": the state is destroyed. A later /v1/scrape with this session_id is refused with 410 ERR::SESSION::RELEASED at 0 credits.

Pitfalls:

  • Idempotent: releasing an already-released session returns 200 with the same body.
  • Releasing an expired session succeeds and marks it released.
  • While a render holds the lease, returns 409 ERR::SESSION::BUSY with Retry-After. Wait, or repeat with force=true to end the session and fail the running task.
  • Takes no body.

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

Path Parameters

sessionID*string

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.

Query Parameters

force?boolean

Set true to end the session even while a render holds its lease; the running task fails. Parsed as a Go boolean (true, false, 1, 0, t, f, any case); other values are refused with 400.

Defaultfalse

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/v1/sessions/01J9ZQ4M7R3T8VX2K5N6P0B1CD/release"
{  "id": "01J9ZQ4M7R3T8VX2K5N6P0B1CD",  "project_id": "string",  "engine": "fetch",  "status": "active",  "sticky_key": "string",  "proxy": {    "tier": "none",    "country": "string",    "region_pool": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "last_used_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "hard_expires_at": "2019-08-24T14:15:22Z",  "released_at": "2019-08-24T14:15:22Z",  "usage_count": 0,  "context": {    "schema_version": 0,    "cookies": 0,    "origins": 0,    "bytes": 0  },  "retired": "expired",  "domain_scores": {    "property1": {      "score": 0,      "good": 0,      "bad": 0,      "last_updated": 0,      "retired": true    },    "property2": {      "score": 0,      "good": 0,      "bad": 0,      "last_updated": 0,      "retired": true    }  },  "fingerprint": {},  "lease": {    "holder": "string",    "expires_at": "2019-08-24T14:15:22Z"  },  "warnings": [    "string"  ]}

Dump the session's cookies and storage GET

The only endpoint that returns credentials. Works only while the session is `active`.

Open a Chrome DevTools Protocol WebSocket to a cloud browser Coming Soon GET

A WebSocket upgrade, not a JSON endpoint. Connect with `puppeteer.connect({browserWSEndpoint})` or `chromium.connectOverCDP(url)`.