```yaml
product: AlterLab
title: "Sessions API Reference — BYOS Authenticated Scraping Endpoints"
comparison_context: "AlterLab is an alternative to Firecrawl, ScrapingBee, and Bright Data."
source_url: https://alterlab.io/docs/api/sessions
```

API Reference

New

# Sessions API

Manage stored browser sessions for programmatic access to your authenticated accounts. 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](https://alterlab.io/docs/guides/authenticated-scraping#security) 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 |
| --- | --- | --- | --- |
| include_shared | `boolean` | Optional | Include shared sessions from the organization.Default: `false` |

#### 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": "john.doe@example.com",
  "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"
```

## Share with Organization

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": "user@example.com",
      "timestamp": "2026-03-18T12:00:00Z",
      "details": {}
    },
    {
      "action": "validated",
      "actor": "user@example.com",
      "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. Pass session_id or cookies inside the advanced object.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| url | `string` | Required | URL to scrape. |
| advanced | `object` | Optional | Advanced options. Pass session_id (UUID of a stored session) or cookies (inline key-value map) inside this object. |

#### 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](https://alterlab.io/docs/reference/error-codes#session-errors) 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](https://alterlab.io/docs/api/rest)[Authenticated Scraping Guide →](https://alterlab.io/docs/guides/authenticated-scraping)

Last updated: June 2026