API Reference

New

Sessions API

Manage stored browser sessions for authenticated web scraping. Create, validate, refresh, and monitor session health across all your target domains.

Base URL

https://api.alterlab.io/api/v1/sessions

Cookie Security

Cookie values are encrypted at rest with AES-256-GCM and are never returned in API responses. Responses include cookie names only, for debugging purposes. See the security section for details.

Authentication

All session endpoints require authentication via API key or JWT bearer token. Sessions are scoped to the authenticated user.

Bash

# API Key
X-API-Key: sk_live_...

# Or JWT Bearer Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Create Session

POST

/api/v1/sessions

Create a new session integration with encrypted cookie storage.

Parameters

Name	Type	Required	Description
name	`string`	Required	Human-readable label for this session (e.g. "My Amazon Prime").
domain	`string`	Required	Target domain (e.g. amazon.com). Protocols and paths are stripped automatically.
cookies	`object`	Required	Key-value map of cookie names to values. Values are encrypted before storage.
headers	`object`	Optional	Optional custom headers to send with authenticated requests.
expires_at	`string`	Optional	Optional ISO-8601 expiration timestamp. AlterLab marks the session as expired after this time.
notes	`string`	Optional	Optional user notes (max 1000 characters).

Request Example

Bash

{
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookies": {
    "session-id": "144-1234567-8901234",
    "session-token": "abc123xyz789..."
  },
  "headers": {
    "Accept-Language": "en-US,en;q=0.9"
  },
  "expires_at": "2026-04-01T00:00:00Z",
  "notes": "Primary US account"
}

Response Example

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookie_names": ["session-id", "session-token"],
  "header_names": ["Accept-Language"],
  "status": "active",
  "expires_at": "2026-04-01T00:00:00Z",
  "last_validated_at": null,
  "validation_confidence": null,
  "consecutive_failures": 0,
  "last_used_at": null,
  "total_requests": 0,
  "successful_requests": 0,
  "success_rate": 0,
  "notes": "Primary US account",
  "created_at": "2026-03-18T12:00:00Z",
  "updated_at": "2026-03-18T12:00:00Z"
}

Python

from alterlab import AlterLabSync

client = AlterLabSync(api_key="YOUR_API_KEY")

session = client.sessions.create(
    name="My Amazon Prime",
    domain="amazon.com",
    cookies={
        "session-id": "144-1234567-8901234",
        "session-token": "abc123xyz789...",
    },
    expires_at="2026-04-01T00:00:00Z",
    notes="Primary US account",
)
print(session["id"])

List Sessions

GET

/api/v1/sessions

List all session integrations for the authenticated user. Supports filtering by domain and status.

Parameters

Name	Type	Required	Description
domain	`string`	Optional	Filter sessions by domain (e.g. amazon.com).
status	`string`	Optional	Filter by status: active, expired, invalid, or pending_validation.

Response Example

JSON

{
  "sessions": [
    {
      "id": "a1b2c3d4-...",
      "name": "My Amazon Prime",
      "domain": "amazon.com",
      "cookie_names": ["session-id", "session-token"],
      "status": "active",
      "consecutive_failures": 0,
      "total_requests": 47,
      "successful_requests": 45,
      "success_rate": 95.7,
      "created_at": "2026-03-18T12:00:00Z",
      "updated_at": "2026-03-18T14:30:00Z"
    }
  ],
  "total": 1
}

Python

# List all sessions
result = client.sessions.list()
for s in result["sessions"]:
    print(f"{s['name']} ({s['domain']}) — {s['status']}")

# Filter by domain
amazon_sessions = client.sessions.list(domain="amazon.com")

# Filter by status
expired = client.sessions.list(status="expired")

Get Session

GET

/api/v1/sessions/{session_id}

Get details for a single session integration. Returns all metadata including health stats.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to retrieve.

Response Example

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookie_names": ["session-id", "session-token"],
  "header_names": ["Accept-Language"],
  "status": "active",
  "expires_at": "2026-04-01T00:00:00Z",
  "last_validated_at": "2026-03-18T14:00:00Z",
  "validation_confidence": 92,
  "consecutive_failures": 0,
  "last_used_at": "2026-03-18T14:30:00Z",
  "total_requests": 47,
  "successful_requests": 45,
  "success_rate": 95.7,
  "notes": "Primary US account",
  "created_at": "2026-03-18T12:00:00Z",
  "updated_at": "2026-03-18T14:30:00Z"
}

Update Session

PATCH

/api/v1/sessions/{session_id}

Update a session integration. Only provided fields are changed. Use refresh for cookie-only rotation with automatic re-validation.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to update.
name	`string`	Optional	New session label.
cookies	`object`	Optional	New cookie name-value mapping. Replaces all cookies.
headers	`object`	Optional	New custom headers. Replaces all headers.
expires_at	`string`	Optional	New expiration timestamp (ISO-8601).
notes	`string`	Optional	New notes.

Request Example

Bash

{
  "name": "Amazon Prime (Refreshed)",
  "expires_at": "2026-05-01T00:00:00Z"
}

Response Example

JSON

{
  "id": "a1b2c3d4-...",
  "name": "Amazon Prime (Refreshed)",
  "domain": "amazon.com",
  "status": "active",
  "expires_at": "2026-05-01T00:00:00Z",
  ...
}

Delete Session

DELETE

/api/v1/sessions/{session_id}

Soft-delete a session integration. The session is marked as inactive but the audit trail is preserved. Returns 204 No Content on success.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to delete.

Python

client.sessions.delete("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

Validate Session

POST

/api/v1/sessions/{session_id}/validate

Validate a session by making a real HTTP request to the target domain using the stored cookies. Checks for logged-in indicators and returns a confidence score.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to validate.

Response Example

JSON

{
  "is_valid": true,
  "confidence": 92,
  "http_status": 200,
  "detected_user": "[email protected]",
  "cookie_expiry_detected": "2026-04-01T00:00:00Z",
  "cookies_expiring_soon": false,
  "indicators_found": {
    "account_links": ["/account", "/orders"],
    "user_elements": ["Hello, John"]
  },
  "consecutive_failures": 0,
  "details": "Session is valid. Detected logged-in user via account menu."
}

Validation Makes Real Requests

Validation sends a real HTTP request to the target domain. This counts as a scrape and uses credits. Use it after creating or refreshing a session, not on every scrape request.

Python

validation = client.sessions.validate("a1b2c3d4-...")
if validation["is_valid"]:
    print(f"Session valid (confidence: {validation['confidence']}%)")
    if validation.get("detected_user"):
        print(f"Logged in as: {validation['detected_user']}")
else:
    print(f"Session invalid: {validation['details']}")

Refresh Session

POST

/api/v1/sessions/{session_id}/refresh

Replace all cookies in a session with fresh ones. Resets consecutive failure counters and sets status back to active. Use this when cookies expire.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to refresh.
cookies	`object`	Required	New cookie name-value mapping. Replaces all existing cookies.
headers	`object`	Optional	Optional new custom headers.

Request Example

Bash

{
  "cookies": {
    "session-id": "new-144-7654321-0987654",
    "session-token": "new-xyz789abc123..."
  }
}

Response Example

JSON

{
  "id": "a1b2c3d4-...",
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookie_names": ["session-id", "session-token"],
  "status": "active",
  "consecutive_failures": 0,
  ...
}

Python

# Refresh with new cookies
updated = client.sessions.refresh(
    "a1b2c3d4-...",
    cookies={
        "session-id": "new-144-7654321-0987654",
        "session-token": "new-xyz789abc123...",
    },
)
print(f"Status: {updated['status']}")  # "active"

PATCH

/api/v1/sessions/{session_id}/share

Share a session with your organization. Requires org admin role. Shared sessions are read-only for non-admin org members — they can use them for scraping but cannot modify or delete them.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to share.
organization_id	`uuid`	Required	UUID of the organization to share with.

Request Example

Bash

{
  "organization_id": "org-uuid-1234-..."
}

Unshare Session

PATCH

/api/v1/sessions/{session_id}/unshare

Remove organization sharing from a session. Requires org admin role.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to unshare.

Audit Log

GET

/api/v1/sessions/{session_id}/audit

Retrieve the audit log for a session. Shows all operations performed on the session with timestamps and actor identity.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session.

Response Example

JSON

{
  "entries": [
    {
      "action": "created",
      "actor": "[email protected]",
      "timestamp": "2026-03-18T12:00:00Z",
      "details": {}
    },
    {
      "action": "validated",
      "actor": "[email protected]",
      "timestamp": "2026-03-18T14:00:00Z",
      "details": { "is_valid": true, "confidence": 92 }
    },
    {
      "action": "used_for_scrape",
      "actor": "system",
      "timestamp": "2026-03-18T14:30:00Z",
      "details": { "url": "https://www.amazon.com/dp/B0EXAMPLE" }
    }
  ],
  "total": 3
}

Scraping with a Session

To use a stored session for scraping, pass the session_id parameter in your scrape request. Alternatively, pass cookies directly for one-off requests.

POST

/api/v1/scrape

Scrape a URL with authenticated session cookies. The session_id and cookies parameters are mutually exclusive.

Parameters

Name	Type	Required	Description
url	`string`	Required	URL to scrape.
session_id	`uuid`	Optional	UUID of a stored session. Domain must match the URL. Mutually exclusive with cookies.
cookies	`object`	Optional	Inline cookie key-value map for one-off use. Not stored. Mutually exclusive with session_id.

Request Example

Bash

{
  "url": "https://www.amazon.com/dp/B0EXAMPLE",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Example

JSON

{
  "url": "https://www.amazon.com/dp/B0EXAMPLE",
  "status_code": 200,
  "content": "<!DOCTYPE html>...",
  "title": "Product Name — Amazon.com",
  "byos_applied": true,
  "billing": {
    "total_credits": 1,
    "tier_used": "1"
  }
}

The response includes "byos_applied": true when session cookies were injected into the request. If the session is expired or invalid, the scrape proceeds without authentication and byos_applied will be false.

Session Object Schema

Field	Type	Description
`id`	uuid	Unique identifier for the session.
`name`	string	User-defined label for the session.
`domain`	string	Target domain. Cookies are only sent to URLs matching this domain.
`cookie_names`	string[]	Names of stored cookies (values are never exposed).
`header_names`	string[] \| null	Names of custom headers, if any.
`status`	enum	One of: `active`, `expired`, `invalid`, `pending_validation`.
`expires_at`	string \| null	ISO-8601 expiration timestamp, if set.
`last_validated_at`	string \| null	Timestamp of the last validation check.
`validation_confidence`	number \| null	Confidence score (0-100) from the last validation.
`consecutive_failures`	number	Number of consecutive failed scrapes with this session.
`last_used_at`	string \| null	Timestamp of the last scrape using this session.
`total_requests`	number	Total scrape requests made with this session.
`successful_requests`	number	Number of successful (authenticated) scrapes.
`success_rate`	number	Success percentage (0-100).
`notes`	string \| null	User notes (max 1000 chars).
`created_at`	string	ISO-8601 creation timestamp.
`updated_at`	string	ISO-8601 last update timestamp.

Error Codes

Code	HTTP	Description	Resolution
`SESSION_NOT_FOUND`	404	The session_id does not exist or belongs to another user.	Verify the UUID. Use `GET /sessions` to list valid sessions.
`SESSION_EXPIRED`	410	Session cookies have expired or the session was marked expired.	Log in again and `POST /sessions/:id/refresh` with fresh cookies.
`SESSION_DOMAIN_MISMATCH`	400	The scrape URL domain does not match the session domain.	Create a separate session for the target domain.
`SESSION_INACTIVE`	410	Session has been deleted or disabled.	Create a new session.
`SESSION_LIMIT_REACHED`	429	Maximum of 50 sessions per account reached.	Delete unused sessions to free up slots.
`SESSION_COOKIES_CONFLICT`	400	Both session_id and cookies were provided in the scrape request.	Use one or the other, not both.

See the full Error Codes Reference for all API error codes.

Rate Limits

Endpoint	Limit	Window
POST /sessions	10 requests	per minute
POST /sessions/:id/validate	5 requests	per minute
POST /sessions/:id/refresh	10 requests	per minute
GET /sessions (list)	30 requests	per minute
Other endpoints	30 requests	per minute

← REST API Reference Authenticated Scraping Guide →

Last updated: March 2026

API Reference

New

Sessions API

Manage stored browser sessions for authenticated web scraping. Create, validate, refresh, and monitor session health across all your target domains.

Base URL

https://api.alterlab.io/api/v1/sessions

Cookie Security

Cookie values are encrypted at rest with AES-256-GCM and are never returned in API responses. Responses include cookie names only, for debugging purposes. See the security section for details.

Authentication

All session endpoints require authentication via API key or JWT bearer token. Sessions are scoped to the authenticated user.

Bash

# API Key
X-API-Key: sk_live_...

# Or JWT Bearer Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Create Session

POST

/api/v1/sessions

Create a new session integration with encrypted cookie storage.

Parameters

Name	Type	Required	Description
name	`string`	Required	Human-readable label for this session (e.g. "My Amazon Prime").
domain	`string`	Required	Target domain (e.g. amazon.com). Protocols and paths are stripped automatically.
cookies	`object`	Required	Key-value map of cookie names to values. Values are encrypted before storage.
headers	`object`	Optional	Optional custom headers to send with authenticated requests.
expires_at	`string`	Optional	Optional ISO-8601 expiration timestamp. AlterLab marks the session as expired after this time.
notes	`string`	Optional	Optional user notes (max 1000 characters).

Request Example

Bash

{
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookies": {
    "session-id": "144-1234567-8901234",
    "session-token": "abc123xyz789..."
  },
  "headers": {
    "Accept-Language": "en-US,en;q=0.9"
  },
  "expires_at": "2026-04-01T00:00:00Z",
  "notes": "Primary US account"
}

Response Example

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookie_names": ["session-id", "session-token"],
  "header_names": ["Accept-Language"],
  "status": "active",
  "expires_at": "2026-04-01T00:00:00Z",
  "last_validated_at": null,
  "validation_confidence": null,
  "consecutive_failures": 0,
  "last_used_at": null,
  "total_requests": 0,
  "successful_requests": 0,
  "success_rate": 0,
  "notes": "Primary US account",
  "created_at": "2026-03-18T12:00:00Z",
  "updated_at": "2026-03-18T12:00:00Z"
}

Python

from alterlab import AlterLabSync

client = AlterLabSync(api_key="YOUR_API_KEY")

session = client.sessions.create(
    name="My Amazon Prime",
    domain="amazon.com",
    cookies={
        "session-id": "144-1234567-8901234",
        "session-token": "abc123xyz789...",
    },
    expires_at="2026-04-01T00:00:00Z",
    notes="Primary US account",
)
print(session["id"])

List Sessions

GET

/api/v1/sessions

List all session integrations for the authenticated user. Supports filtering by domain and status.

Parameters

Name	Type	Required	Description
domain	`string`	Optional	Filter sessions by domain (e.g. amazon.com).
status	`string`	Optional	Filter by status: active, expired, invalid, or pending_validation.

Response Example

JSON

{
  "sessions": [
    {
      "id": "a1b2c3d4-...",
      "name": "My Amazon Prime",
      "domain": "amazon.com",
      "cookie_names": ["session-id", "session-token"],
      "status": "active",
      "consecutive_failures": 0,
      "total_requests": 47,
      "successful_requests": 45,
      "success_rate": 95.7,
      "created_at": "2026-03-18T12:00:00Z",
      "updated_at": "2026-03-18T14:30:00Z"
    }
  ],
  "total": 1
}

Python

# List all sessions
result = client.sessions.list()
for s in result["sessions"]:
    print(f"{s['name']} ({s['domain']}) — {s['status']}")

# Filter by domain
amazon_sessions = client.sessions.list(domain="amazon.com")

# Filter by status
expired = client.sessions.list(status="expired")

Get Session

GET

/api/v1/sessions/{session_id}

Get details for a single session integration. Returns all metadata including health stats.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to retrieve.

Response Example

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookie_names": ["session-id", "session-token"],
  "header_names": ["Accept-Language"],
  "status": "active",
  "expires_at": "2026-04-01T00:00:00Z",
  "last_validated_at": "2026-03-18T14:00:00Z",
  "validation_confidence": 92,
  "consecutive_failures": 0,
  "last_used_at": "2026-03-18T14:30:00Z",
  "total_requests": 47,
  "successful_requests": 45,
  "success_rate": 95.7,
  "notes": "Primary US account",
  "created_at": "2026-03-18T12:00:00Z",
  "updated_at": "2026-03-18T14:30:00Z"
}

Update Session

PATCH

/api/v1/sessions/{session_id}

Update a session integration. Only provided fields are changed. Use refresh for cookie-only rotation with automatic re-validation.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to update.
name	`string`	Optional	New session label.
cookies	`object`	Optional	New cookie name-value mapping. Replaces all cookies.
headers	`object`	Optional	New custom headers. Replaces all headers.
expires_at	`string`	Optional	New expiration timestamp (ISO-8601).
notes	`string`	Optional	New notes.

Request Example

Bash

{
  "name": "Amazon Prime (Refreshed)",
  "expires_at": "2026-05-01T00:00:00Z"
}

Response Example

JSON

{
  "id": "a1b2c3d4-...",
  "name": "Amazon Prime (Refreshed)",
  "domain": "amazon.com",
  "status": "active",
  "expires_at": "2026-05-01T00:00:00Z",
  ...
}

Delete Session

DELETE

/api/v1/sessions/{session_id}

Soft-delete a session integration. The session is marked as inactive but the audit trail is preserved. Returns 204 No Content on success.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to delete.

Python

client.sessions.delete("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

Validate Session

POST

/api/v1/sessions/{session_id}/validate

Validate a session by making a real HTTP request to the target domain using the stored cookies. Checks for logged-in indicators and returns a confidence score.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to validate.

Response Example

JSON

{
  "is_valid": true,
  "confidence": 92,
  "http_status": 200,
  "detected_user": "[email protected]",
  "cookie_expiry_detected": "2026-04-01T00:00:00Z",
  "cookies_expiring_soon": false,
  "indicators_found": {
    "account_links": ["/account", "/orders"],
    "user_elements": ["Hello, John"]
  },
  "consecutive_failures": 0,
  "details": "Session is valid. Detected logged-in user via account menu."
}

Validation Makes Real Requests

Validation sends a real HTTP request to the target domain. This counts as a scrape and uses credits. Use it after creating or refreshing a session, not on every scrape request.

Python

validation = client.sessions.validate("a1b2c3d4-...")
if validation["is_valid"]:
    print(f"Session valid (confidence: {validation['confidence']}%)")
    if validation.get("detected_user"):
        print(f"Logged in as: {validation['detected_user']}")
else:
    print(f"Session invalid: {validation['details']}")

Refresh Session

POST

/api/v1/sessions/{session_id}/refresh

Replace all cookies in a session with fresh ones. Resets consecutive failure counters and sets status back to active. Use this when cookies expire.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to refresh.
cookies	`object`	Required	New cookie name-value mapping. Replaces all existing cookies.
headers	`object`	Optional	Optional new custom headers.

Request Example

Bash

{
  "cookies": {
    "session-id": "new-144-7654321-0987654",
    "session-token": "new-xyz789abc123..."
  }
}

Response Example

JSON

{
  "id": "a1b2c3d4-...",
  "name": "My Amazon Prime",
  "domain": "amazon.com",
  "cookie_names": ["session-id", "session-token"],
  "status": "active",
  "consecutive_failures": 0,
  ...
}

Python

# Refresh with new cookies
updated = client.sessions.refresh(
    "a1b2c3d4-...",
    cookies={
        "session-id": "new-144-7654321-0987654",
        "session-token": "new-xyz789abc123...",
    },
)
print(f"Status: {updated['status']}")  # "active"

PATCH

/api/v1/sessions/{session_id}/share

Share a session with your organization. Requires org admin role. Shared sessions are read-only for non-admin org members — they can use them for scraping but cannot modify or delete them.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to share.
organization_id	`uuid`	Required	UUID of the organization to share with.

Request Example

Bash

{
  "organization_id": "org-uuid-1234-..."
}

Unshare Session

PATCH

/api/v1/sessions/{session_id}/unshare

Remove organization sharing from a session. Requires org admin role.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session to unshare.

Audit Log

GET

/api/v1/sessions/{session_id}/audit

Retrieve the audit log for a session. Shows all operations performed on the session with timestamps and actor identity.

Parameters

Name	Type	Required	Description
session_id	`uuid`	Required	UUID of the session.

Response Example

JSON

{
  "entries": [
    {
      "action": "created",
      "actor": "[email protected]",
      "timestamp": "2026-03-18T12:00:00Z",
      "details": {}
    },
    {
      "action": "validated",
      "actor": "[email protected]",
      "timestamp": "2026-03-18T14:00:00Z",
      "details": { "is_valid": true, "confidence": 92 }
    },
    {
      "action": "used_for_scrape",
      "actor": "system",
      "timestamp": "2026-03-18T14:30:00Z",
      "details": { "url": "https://www.amazon.com/dp/B0EXAMPLE" }
    }
  ],
  "total": 3
}

Scraping with a Session

To use a stored session for scraping, pass the session_id parameter in your scrape request. Alternatively, pass cookies directly for one-off requests.

POST

/api/v1/scrape

Scrape a URL with authenticated session cookies. The session_id and cookies parameters are mutually exclusive.

Parameters

Name	Type	Required	Description
url	`string`	Required	URL to scrape.
session_id	`uuid`	Optional	UUID of a stored session. Domain must match the URL. Mutually exclusive with cookies.
cookies	`object`	Optional	Inline cookie key-value map for one-off use. Not stored. Mutually exclusive with session_id.

Request Example

Bash

{
  "url": "https://www.amazon.com/dp/B0EXAMPLE",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Example

JSON

{
  "url": "https://www.amazon.com/dp/B0EXAMPLE",
  "status_code": 200,
  "content": "<!DOCTYPE html>...",
  "title": "Product Name — Amazon.com",
  "byos_applied": true,
  "billing": {
    "total_credits": 1,
    "tier_used": "1"
  }
}

Session Object Schema

Field	Type	Description
`id`	uuid	Unique identifier for the session.
`name`	string	User-defined label for the session.
`domain`	string	Target domain. Cookies are only sent to URLs matching this domain.
`cookie_names`	string[]	Names of stored cookies (values are never exposed).
`header_names`	string[] \| null	Names of custom headers, if any.
`status`	enum	One of: `active`, `expired`, `invalid`, `pending_validation`.
`expires_at`	string \| null	ISO-8601 expiration timestamp, if set.
`last_validated_at`	string \| null	Timestamp of the last validation check.
`validation_confidence`	number \| null	Confidence score (0-100) from the last validation.
`consecutive_failures`	number	Number of consecutive failed scrapes with this session.
`last_used_at`	string \| null	Timestamp of the last scrape using this session.
`total_requests`	number	Total scrape requests made with this session.
`successful_requests`	number	Number of successful (authenticated) scrapes.
`success_rate`	number	Success percentage (0-100).
`notes`	string \| null	User notes (max 1000 chars).
`created_at`	string	ISO-8601 creation timestamp.
`updated_at`	string	ISO-8601 last update timestamp.

Error Codes

Code	HTTP	Description	Resolution
`SESSION_NOT_FOUND`	404	The session_id does not exist or belongs to another user.	Verify the UUID. Use `GET /sessions` to list valid sessions.
`SESSION_EXPIRED`	410	Session cookies have expired or the session was marked expired.	Log in again and `POST /sessions/:id/refresh` with fresh cookies.
`SESSION_DOMAIN_MISMATCH`	400	The scrape URL domain does not match the session domain.	Create a separate session for the target domain.
`SESSION_INACTIVE`	410	Session has been deleted or disabled.	Create a new session.
`SESSION_LIMIT_REACHED`	429	Maximum of 50 sessions per account reached.	Delete unused sessions to free up slots.
`SESSION_COOKIES_CONFLICT`	400	Both session_id and cookies were provided in the scrape request.	Use one or the other, not both.

See the full Error Codes Reference for all API error codes.

Rate Limits

Endpoint	Limit	Window
POST /sessions	10 requests	per minute
POST /sessions/:id/validate	5 requests	per minute
POST /sessions/:id/refresh	10 requests	per minute
GET /sessions (list)	30 requests	per minute
Other endpoints	30 requests	per minute

← REST API Reference Authenticated Scraping Guide →

Last updated: March 2026

Sessions API

Authentication

Create Session

Parameters

Request Example

Response Example

List Sessions

Parameters

Response Example

Get Session

Parameters

Response Example

Update Session

Parameters

Request Example

Response Example

Delete Session

Parameters

Validate Session

Parameters

Response Example

Refresh Session

Parameters

Request Example

Response Example

Share with Organization

Parameters

Request Example

Unshare Session

Parameters

Audit Log

Parameters

Response Example

Scraping with a Session

Parameters

Request Example

Response Example

Session Object Schema

Error Codes

Rate Limits

Sessions API

Authentication

Create Session

Parameters

Request Example

Response Example

List Sessions

Parameters

Response Example

Get Session

Parameters

Response Example

Update Session

Parameters

Request Example

Response Example

Delete Session

Parameters

Validate Session

Parameters

Response Example

Refresh Session

Parameters

Request Example

Response Example

Share with Organization

Parameters

Request Example

Unshare Session

Parameters

Audit Log

Parameters

Response Example

Scraping with a Session

Parameters

Request Example

Response Example

Session Object Schema

Error Codes

Rate Limits