Sessions

Create a persisted browser session

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

Pitfalls:

  • Every field is optional. An empty body (Content-Length 0) means "all defaults"; {} also works. Unknown fields are refused with 400.
  • Sessions are single-writer. While a render holds the lease, a second scrape on the same session, and release/delete without force=true, get 409 ERR::SESSION::BUSY with a Retry-After. Serialise work per session, or create one session per concurrent worker.
  • rotate_ip and sticky_key are mutually exclusive (400 ERR::REQUEST::INCOMPATIBLE_FLAGS). Omitting both pins the exit: sticky_key is derived from the session id.
  • ttl_seconds above the organization's maximum is refused (400), never clamped. It slides on use but never past hard_expires_at.
  • proxy_country requires premium_proxy: true. fingerprint is an advanced option and may be refused with 400.
  • A project may hold only one active session per sticky_key (409 ERR::REQUEST::CONFLICT).
  • An organization may hold at most 100 live sessions (429 ERR::LIMIT::SESSIONS_EXCEEDED, Retry-After 30).
  • engine is optional (fetch, js or browser): omit it and the session's rendering is chosen for you. Scrapes with the session run on that tier, so a js session refuses actions, block_resources, a screenshot and a PDF (400 ERR::REQUEST::CAPABILITY_UNSUPPORTED).
post/v1/sessions

Request

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

Request body

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.

ttl_secondsinteger

Sliding lifetime in seconds. Omitted or 0 means 1800, reduced to the organization maximum with a warning if that is lower. Values above the organization maximum (default 604800, i.e. 7 days) are refused with 400 naming the real maximum.

sticky_keystring

Coming soon. Pins the exit IP across the session. Letters, digits and hyphens, not starting or ending with a hyphen. Omitted means derived from the session id (still pinned). Must be unique among active sessions in the project. Cannot be combined with rotate_ip.

region_poolstring

Coming soon. Regional exit pool to draw from. Trimmed; longer than 64 characters is refused.

rotate_ipboolean

Coming soon. Keep the cookie jar but let the exit IP change between requests. Use for many-page crawls; avoid for replayed logins, which get challenged on a moving IP. Refused together with sticky_key.

premium_proxyboolean

Coming soon. Use the residential tier instead of datacenter. Same meaning as on /v1/scrape.

proxy_countrystring

Coming soon. ISO 3166-1 alpha-2 exit country, case-insensitive. Requires premium_proxy: true, otherwise 400 ERR::REQUEST::INCOMPATIBLE_FLAGS.

fingerprintobject nullable

Browser fingerprint pin, stored verbatim. Advanced option; a non-empty object is refused with 400 where the session's rendering cannot apply it. null and {} count as absent.

domain_scoresobject

Seed per-domain health, keyed by lowercase registrable domain (e.g. example.com). Scores must be non-negative. Above 64 entries, the least useful (unblocked, lowest score, oldest) are evicted rather than refused.

Response

Session created. Use id as session_id on /v1/scrape. Read warnings for any decision made on your behalf (e.g. a reduced default TTL).

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.