POST/v1/sessions

Create Session

Launch a new isolated browser session with stealth configuration, proxy, and fingerprint.

Proxy configuration for the session.

Proxy type. One of: residential, datacenter, isp, mobile.

ISO 3166-1 alpha-2 country code (e.g., US, GB, DE).

Geographic region: us, eu, asia, latam.

City name (e.g., New York, London). Requires country.

Use the same IP for the session duration.

Anti-detection level. One of: none, basic, max (alias: full).

Set to auto for automatic fingerprint generation, or provide a custom config.

OS platform: Win32, MacIntel, Linux x86_64.

Custom User-Agent string.

Browser locale (e.g., en-US).

IANA timezone (e.g., America/New_York).

Browser viewport { width, height }.

Attach an existing profile to restore cookies and storage.

Session TTL in seconds. Auto-destroys after this duration. Max: 3600.

Enable session recording.

Capture network requests as HAR file.

Capture periodic screenshots.

Record full video of the session.

Request

curl --request POST \
  --url https://api.sessionkit.dev/v1/sessions \
  --header 'Authorization: Bearer sk_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "proxy": { "type": "residential", "country": "US", "sticky": true },
  "stealth": "max",
  "fingerprint": "auto",
  "timeout": 300
}'

from sessionkit import SessionKit

sk = SessionKit(api_key="sk_live_...")

session = sk.sessions.create(
    proxy={"type": "residential", "country": "US", "sticky": True},
    stealth="max",
    fingerprint="auto",
    timeout=300,
)

import { SessionKit } from '@sessionkit/sdk'

const sk = new SessionKit({ apiKey: 'sk_live_...' })

const session = await sk.sessions.create({
  proxy: { type: 'residential', country: 'US', sticky: true },
  stealth: 'max',
  fingerprint: 'auto',
  timeout: 300,
})

$sk = new \SessionKit\Client('sk_live_...');

$session = $sk->sessions->create([
    'proxy' => ['type' => 'residential', 'country' => 'US', 'sticky' => true],
    'stealth' => 'max',
    'fingerprint' => 'auto',
    'timeout' => 300,
]);

sk := sessionkit.New("sk_live_...")

session, err := sk.Sessions.Create(context.Background(), &sessionkit.CreateSessionParams{
    Proxy:       &sessionkit.Proxy{Type: "residential", Country: "US", Sticky: true},
    Stealth:     "max",
    Fingerprint: "auto",
    Timeout:     300,
})

SessionKit sk = new SessionKit("sk_live_...");

Session session = sk.sessions().create(CreateSessionRequest.builder()
    .proxy(Proxy.builder().type("residential").country("US").sticky(true).build())
    .stealth("max")
    .fingerprint("auto")
    .timeout(300)
    .build());

sk = SessionKit::Client.new(api_key: "sk_live_...")

session = sk.sessions.create(
  proxy: { type: "residential", country: "US", sticky: true },
  stealth: "max",
  fingerprint: "auto",
  timeout: 300
)

Response

Unique session identifier (prefixed ses_).

Current status: active, idle, terminated.

WebSocket URL for Chrome DevTools Protocol connection. Includes auth token.

Resolved proxy configuration including the assigned IP address.

Generated or configured fingerprint applied to the session.

ISO 8601 timestamp when the session will auto-terminate.

{
  "id": "ses_k8m2n4p6",
  "status": "active",
  "cdpUrl": "wss://api.sessionkit.dev/cdp/ses_k8m2n4p6?token=ct_abc123",
  "proxy": {
    "type": "residential",
    "country": "US",
    "ip": "184.xxx.xxx.xxx"
  },
  "fingerprint": {
    "platform": "Win32",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
  },
  "expiresAt": "2026-06-23T15:30:00Z"
}

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "proxy.type must be one of: residential, datacenter, isp, mobile",
    "details": { "field": "proxy.type", "value": "invalid" }
  }
}

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly session quota exceeded. Upgrade plan at https://sessionkit.dev/billing"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have permission to create sessions"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 2 seconds",
    "details": { "retryAfter": 2 }
  }
}