AlterLabAPI 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/sessionsCookie 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/sessionsCreate 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/sessionsList 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}/validateValidate 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}/refreshReplace 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}/shareShare 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}/unshareRemove 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}/auditRetrieve 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/scrapeScrape 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 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 |