Create Browser Session

POST

/api/v1/cloud-browser/sessions

Requires a login JWT; API keys are not accepted. Generate requestId for each new operation; reuse it with an identical body for retries. Changed configuration requires a new ID. Poll the returned session until ready; creating or unknown must not trigger replacement creation. Configure proxy, fingerprint, CAPTCHA and recording at creation. Reconnecting does not extend ttlSeconds.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Successful operation. Business data is in data; err, code and msg remain in the envelope. Inspect the response for state and availability.

Headers

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🟠409

🟠410

🟠413

🟠422

🟠429

🟠470

🔴500

🔴503

⚪default

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/cloud-browser/sessions' \
--header 'x-team-id;' \
--header 'X-Client-Source;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "11111111-1111-4111-8111-111111111111",
    "name": "api-example",
    "resourceClass": "lite",
    "ttlSeconds": 300,
    "targetUrl": "https://example.com/",
    "proxyCountry": "ANY",
    "recording": false,
    "captchaSolver": {
        "enabled": false
    }
}'

Response Example

200 - Example 1

{
    "data": {
        "failurePhase": "before_ready",
        "recordingAvailability": {
            "state": "disabled",
            "stale": true,
            "observedAt": "2019-08-24T14:15:22.123Z",
            "expiresAt": "2019-08-24T14:15:22.123Z",
            "deletedAt": "2019-08-24T14:15:22.123Z",
            "deleteRequestedAt": "2019-08-24T14:15:22.123Z",
            "segmentCount": 0,
            "readyDomSegmentCount": 0
        },
        "providerObservation": {
            "observedAt": "2019-08-24T14:15:22.123Z",
            "configurationRevision": 0,
            "appliedFingerprintSha256": "string",
            "networkIdentity": {
                "observedAt": "2019-08-24T14:15:22.123Z",
                "alignmentStatus": "aligned",
                "ip": "string",
                "countryCode": "string",
                "locale": "string",
                "timezone": "string",
                "latitude": -90,
                "longitude": -180,
                "resolvedAt": "2019-08-24T14:15:22.123Z"
            },
            "timingsMs": {
                "property1": 0,
                "property2": 0
            }
        },
        "effectiveConfiguration": {
            "resourceClass": "string",
            "ttlSeconds": 0,
            "recording": true,
            "maskInputs": true,
            "proxyConfigured": true,
            "proxyGeoIp": true,
            "geoIpGeolocation": true,
            "geoIpStatus": "disabled",
            "fingerprint": {
                "platform": "windows",
                "kernelMilestone": "string",
                "platformVersion": "string",
                "resolution": "600x666",
                "locale": "string",
                "timezone": "string",
                "userAgent": "string"
            },
            "extensions": [
                {
                    "artifactId": "string",
                    "version": "string",
                    "enabled": true
                }
            ]
        },
        "warnings": [
            "string"
        ],
        "captchaSolver": {
            "enabled": false,
            "types": {
                "recaptchaV2": true,
                "recaptchaV3": true,
                "textCaptcha": true,
                "awsCaptcha": true,
                "cloudflareTurnstile": true
            },
            "artifactId": "string",
            "version": "string"
        },
        "captchaEnabled": true,
        "source": "dash",
        "proxyRegion": "string",
        "captchaSuccesses": 0,
        "proxyTrafficBytes": "string",
        "navigationState": "pending",
        "navigationAttempts": 0,
        "navigationErrorCode": "string",
        "targetUrl": "string",
        "proxyCountry": "string",
        "sessionId": "string",
        "name": "string",
        "state": "creating",
        "resourceClass": "string",
        "region": "string",
        "ttlSeconds": 0,
        "recording": true,
        "maskInputs": true,
        "recordingId": "string",
        "readyAt": "2019-08-24T14:15:22.123Z",
        "expiresAt": "2019-08-24T14:15:22.123Z",
        "endedAt": "2019-08-24T14:15:22.123Z",
        "createdAt": "2019-08-24T14:15:22.123Z",
        "errorCode": "string",
        "endReason": "client_release",
        "billableStartedAt": "2019-08-24T14:15:22.123Z",
        "billableEndedAt": "2019-08-24T14:15:22.123Z",
        "billingState": "string",
        "usageSeconds": 0,
        "amount": "string",
        "ledgerId": "string"
    },
    "err": false,
    "code": 200,
    "msg": "SUCCESS"
}

Modified at 2026-10-28 10:42:27

Estimate Browser Runtime Cost

List Browser Sessions