Sessions

Get one session's metadata

Returns the session's metadata and a non-secret context summary. Never returns cookies, and does not slide the TTL, so it is safe to poll. Released and expired sessions are still returned (200) with their status; only a deleted or unknown session is 404. A malformed id also answers 404 ERR::SESSION::NOT_FOUND.

get/v1/sessions/{sessionID}

Request

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

Response

The session.

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.