Sessions

End a session and purge its context

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.
post/v1/sessions/{sessionID}/release

Request

  • Base URL: https://api.spicrawl.com
  • URL: https://api.spicrawl.com/v1/sessions/{sessionID}/release
  • Auth: HTTP bearer

Query parameters

forceboolean

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.

Response

The session, now released, with context null.

idstring required

Session id (26-character ULID). Pass it as session_id on /v1/scrape.

project_idstring 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_keystring required

Exit pin in use. The lowercase session id when you did not set one; empty string when rotate_ip was set.

created_atstring date-time required

Creation time, RFC 3339 UTC.

last_used_atstring date-time nullable required

Last time a successful scrape used the session. Null means never used.

expires_atstring 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_atstring 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_atstring date-time

When the session was released. Present only on released sessions.

usage_countinteger required

Number of successful scrapes that have used the session. Failed scrapes and /context reads do not count.

retired'expired' | 'usage_exhausted' | 'explicit'

Why a worker took this session out of service. Absent while usable. A retired session should be replaced.

domain_scoresobject

Per-domain block evidence the workers maintain. Omitted when empty.

fingerprintobject

Browser fingerprint, as stored. Omitted when none was set.

warningsstring[]

Decisions made on your behalf at creation, e.g. a TTL reduced to the organization maximum. Only on the create response; omitted when empty.

Example response

{
  "id": "01J9ZQ4M7R3T8VX2K5N6P0B1CD"
}

Changes

No recorded changes to this operation across all 1 revision of this API.