Create a Browser Session

POST/v1/browser/sessions

Creates one Team-scoped Browser Session, waits until the browser-level relay is ready, and returns the active resource. The request is Team-billed at 120 Credits/hour, rounded up at 1 Credit per 30 actual active seconds. The full TTL is reserved before startup and unused Credits are released on stop. Per-Team Profile/concurrent Session limits are Free 5/1, Starter 20/2, Scale 100/4, Enterprise 200/4. Each Free Team without an assigned billing period receives 5,000 included Credits per UTC calendar month. Idle Profiles are free. Profile use is exclusive, and Idempotency-Key is mandatory. After authentication and request validation, replay precedes new-resource Profile, runtime, and quota checks. Accepted startup survives HTTP disconnect but retains its original 60-second deadline; a late provider result is cleaned up and cannot activate the Session.

On this page

Request example

Replace placeholders with your values. Use your Team API key for authenticated requests.

API base https://kieapi.com

curl -X POST "https://kieapi.com/v1/browser/sessions" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{}'

Authentication

BearerAuth

Parameters

Idempotency-Key header · string required: Required caller-generated key for exactly-once Browser Session creation within the bound Team. Same-body replay returns the same Session; a different body or an in-progress operation returns 409.

Request body required

application/json

BrowserSessionCreateRequest

proxy BrowserProxySelection or null: Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy.
profile_id string | null: Persistent Profile to lock exclusively for the Session.
proxy_id string | null: Team-authorized Proxy. It cannot override a Profile-bound Proxy.
ttl_seconds integer: Default: 300
device_profile string | null: Disposable Session device class. Omit when profile_id is supplied.
Allowed: "auto", "windows", "macos", "linux", "android", "ios", null

Responses

201 Browser session created.

application/json

BrowserSessionCreateResponse

session BrowserSession required

400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

402 The Team does not have enough available Credits for the maximum reservation.

application/json

PublicErrorResponse

error PublicError required

403 Authenticated principal cannot access this resource.

application/json

PublicErrorResponse

error PublicError required

404 Browser profile was not found or is not visible to this workspace.

application/json

PublicErrorResponse

error PublicError required

409 Browser resource state, idempotency, Proxy authority, or controller ownership conflicts with this request.

application/json

PublicErrorResponse

error PublicError required

422 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

429 Temporary rate limit.

application/json

PublicErrorResponse

error PublicError required

503 Required runtime service is unavailable.

application/json

PublicErrorResponse

error PublicError required

504 Work timed out.

application/json

PublicErrorResponse

error PublicError required

Schemas

Field definitions and complete validation rules for this API. Follow a type link to its definition.

BrowserSessionCreateRequest

object

proxy BrowserProxySelection or null: Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy.
profile_id string | null: Persistent Profile to lock exclusively for the Session.
proxy_id string | null: Team-authorized Proxy. It cannot override a Profile-bound Proxy.
ttl_seconds integer: Default: 300
device_profile string | null: Disposable Session device class. Omit when profile_id is supplied.
Allowed: "auto", "windows", "macos", "linux", "android", "ios", null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "proxy": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserProxySelection"
        },
        {
          "type": "null"
        }
      ],
      "description": "Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy."
    },
    "profile_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128,
      "description": "Persistent Profile to lock exclusively for the Session."
    },
    "proxy_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128,
      "description": "Team-authorized Proxy. It cannot override a Profile-bound Proxy."
    },
    "ttl_seconds": {
      "type": "integer",
      "minimum": 30,
      "maximum": 3600,
      "default": 300
    },
    "device_profile": {
      "type": [
        "string",
        "null"
      ],
      "description": "Disposable Session device class. Omit when profile_id is supplied.",
      "enum": [
        "auto",
        "windows",
        "macos",
        "linux",
        "android",
        "ios",
        null
      ]
    }
  }
}

BrowserProxySelection

object

Exactly one mode: direct has no extra fields; system_dynamic requires a published country and optional published sticky_minutes; account_static/custom_proxy require resource_id and may specify required_country. Credentials are never accepted.

mode string required: Allowed: "direct", "system_dynamic", "account_static", "custom_proxy"
country string or null: Default: null
sticky_minutes integer or null: Default: null
resource_id string or null: Default: null
required_country string or null: Default: null

Complete schema

{
  "additionalProperties": false,
  "description": "Exactly one mode: direct has no extra fields; system_dynamic requires a published country and optional published sticky_minutes; account_static/custom_proxy require resource_id and may specify required_country. Credentials are never accepted.",
  "properties": {
    "mode": {
      "enum": [
        "direct",
        "system_dynamic",
        "account_static",
        "custom_proxy"
      ],
      "title": "Mode",
      "type": "string"
    },
    "country": {
      "anyOf": [
        {
          "maxLength": 2,
          "minLength": 2,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Country"
    },
    "sticky_minutes": {
      "anyOf": [
        {
          "enum": [
            5,
            10,
            30
          ],
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sticky Minutes"
    },
    "resource_id": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Id"
    },
    "required_country": {
      "anyOf": [
        {
          "maxLength": 2,
          "minLength": 2,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Required Country"
    }
  },
  "required": [
    "mode"
  ],
  "type": "object"
}

BrowserSessionCreateResponse

object

session BrowserSession required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "session"
  ],
  "properties": {
    "session": {
      "$ref": "#/components/schemas/BrowserSession"
    }
  }
}

BrowserSession

object

proxy_usage BrowserProxyUsage or null
proxy BrowserProxySelection or null: Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy.
id string required
status string required: Allowed: "active", "stopping", "saving_profile", "stopped", "stopped_with_profile_error"
profile_id string | null required
proxy_id string | null required
device_profile string required: Allowed: "auto", "windows", "macos", "linux", "android", "ios"
ttl_seconds integer required
created_at string (date-time) required
active_at string (date-time) required
expires_at string (date-time) required: Browser Session TTL expiry. The connection ticket has its own earlier expiry.
ended_at string | null (date-time) required: First accepted termination time, capped at expires_at. A first stop at or after expiry uses ttl_expired; later stops never overwrite its reason. Cleanup time is not billed.
profile_save_recovered_at string | null (date-time) required: Set only when an earlier persistent Profile save failure was automatically reverified and recovered.
termination_reason string | null required: Allowed: "client_request", "ttl_expired", "team_suspended", "runtime_failure", "administrative_stop", "unknown", null
connect_url string | null required: POST this route to mint a one-time controller ticket; null once the Session is no longer active.
usage BrowserSessionUsage or null required
failure BrowserSessionFailure or null required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "profile_id",
    "proxy_id",
    "device_profile",
    "ttl_seconds",
    "created_at",
    "active_at",
    "expires_at",
    "ended_at",
    "profile_save_recovered_at",
    "termination_reason",
    "connect_url",
    "usage",
    "failure"
  ],
  "properties": {
    "proxy_usage": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserProxyUsage"
        },
        {
          "type": "null"
        }
      ]
    },
    "proxy": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserProxySelection"
        },
        {
          "type": "null"
        }
      ],
      "description": "Four-mode network intent. Do not combine with non-null legacy proxy_id. Session creation with profile_id inherits the Profile and must omit proxy."
    },
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "stopping",
        "saving_profile",
        "stopped",
        "stopped_with_profile_error"
      ]
    },
    "profile_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "proxy_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "device_profile": {
      "type": "string",
      "enum": [
        "auto",
        "windows",
        "macos",
        "linux",
        "android",
        "ios"
      ]
    },
    "ttl_seconds": {
      "type": "integer",
      "minimum": 30,
      "maximum": 3600
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "active_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "Browser Session TTL expiry. The connection ticket has its own earlier expiry."
    },
    "ended_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "First accepted termination time, capped at expires_at. A first stop at or after expiry uses ttl_expired; later stops never overwrite its reason. Cleanup time is not billed."
    },
    "profile_save_recovered_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Set only when an earlier persistent Profile save failure was automatically reverified and recovered."
    },
    "termination_reason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "client_request",
        "ttl_expired",
        "team_suspended",
        "runtime_failure",
        "administrative_stop",
        "unknown",
        null
      ]
    },
    "connect_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "POST this route to mint a one-time controller ticket; null once the Session is no longer active."
    },
    "usage": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserSessionUsage"
        },
        {
          "type": "null"
        }
      ]
    },
    "failure": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/BrowserSessionFailure"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

BrowserProxyUsage

object

billable_response_bytes integer

Default: 0

credits_charged integer or null

Default: null

charge_status string

Allowed: "pending", "charged", "not_charged"

Default: "pending"

actual_country string or null

Default: null

exit_ip string or null

Default: null

measurement_interrupted boolean

Default: false

Complete schema

{
  "properties": {
    "billable_response_bytes": {
      "default": 0,
      "minimum": 0,
      "title": "Billable Response Bytes",
      "type": "integer"
    },
    "credits_charged": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Credits Charged"
    },
    "charge_status": {
      "default": "pending",
      "enum": [
        "pending",
        "charged",
        "not_charged"
      ],
      "title": "Charge Status",
      "type": "string"
    },
    "actual_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Actual Country"
    },
    "exit_ip": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Exit Ip"
    },
    "measurement_interrupted": {
      "default": false,
      "title": "Measurement Interrupted",
      "type": "boolean"
    }
  },
  "type": "object",
  "additionalProperties": false
}

BrowserSessionUsage

object

billable_seconds integer required
credits_charged integer required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "billable_seconds",
    "credits_charged"
  ],
  "properties": {
    "billable_seconds": {
      "type": "integer",
      "minimum": 0
    },
    "credits_charged": {
      "type": "integer",
      "minimum": 0
    }
  }
}

BrowserSessionFailure

object

code string required: Allowed: "browser_runtime_lost", "browser_relay_lost", "profile_save_failed"
occurred_at string (date-time) required
recovered_at string | null (date-time) required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "occurred_at",
    "recovered_at"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "browser_runtime_lost",
        "browser_relay_lost",
        "profile_save_failed"
      ]
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time"
    },
    "recovered_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

PublicErrorResponse

object

error PublicError required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "$ref": "#/components/schemas/PublicError"
    }
  }
}

PublicError

object

code string required: Allowed: "seoapi_price_pending", "seoapi_unavailable", "seoapi_busy", "seoapi_not_found", "seoapi_rate_limited", "seoapi_budget_exceeded", "seoapi_idempotency_conflict", "seoapi_insufficient_credits", "seoapi_admission_failed", "seoapi_execution_interrupted", "seoapi_delivery_unknown", "seoapi_response_invalid", "seoapi_model_unsupported", "seoapi_model_options_invalid", "seoapi_provider_rejected", "seo_price_pending", "seo_provider_blocked", "seo_local_rate_limited", "seo_fallback_unavailable", "seo_fallback_budget_exceeded", "seo_pagination_expired", "seo_delivery_uncertain", "seo_auth_required", "seo_initialization_required", "seo_permission_denied", "seo_verification_required", "seo_rate_limited", "seo_upstream_unavailable", "seo_transport_failed", "seo_invalid_response", "seo_rpc_error", "seo_period_unavailable", "seo_account_unavailable", "seo_session_busy", "seo_configuration_required", "validation_error", "invalid_request", "unsupported_feature", "authentication_required", "permission_denied", "not_found", "run_not_found", "crawl_not_found", "artifact_not_found", "session_not_found", "profile_not_found", "profile_in_use", "profile_not_ready", "profile_not_cloneable", "profile_limit_reached", "profile_proxy_conflict", "proxy_not_found", "proxy_unavailable", "invalid_session_options", "invalid_query_options", "invalid_cursor", "idempotency_key_required", "browser_session_limit_reached", "browser_capacity_exhausted", "browser_start_timeout", "browser_runtime_unavailable", "session_not_active", "controller_already_connected", "browser_relay_unavailable", "precondition_required", "precondition_failed", "timeout", "run_not_ready", "artifact_expired", "quota_exceeded", "insufficient_credits", "billing_reconciliation_required", "rate_limited", "fetch_failed", "render_failed", "maps_rate_limited", "maps_challenge", "maps_schema_changed", "maps_invalid_response", "maps_transport_failed", "maps_page_budget_exhausted", "google_trends_rate_limited", "google_trends_challenge", "google_trends_explore_failed", "google_trends_widget_missing", "google_trends_related_failed", "google_trends_invalid_response", "google_trends_transport_failed", "google_trends_collection_failed", "google_ads_account_context_missing", "google_ads_batch_failed", "google_ads_browser_context_missing", "google_ads_browser_unavailable", "google_ads_collection_failed", "google_ads_page_failed", "google_ads_protocol_drift", "google_ads_rate_limited", "google_ads_timeout", "twitter_provider_unavailable", "twitter_provider_rejected", "twitter_submission_unknown", "wechat_transport_failed", "wechat_rate_limited", "wechat_invalid_response", "wechat_redirect_rejected", "wechat_verification_required", "wechat_parse_failed", "blackhatworld_search_failed", "blackhatworld_no_results", "reddit_read_failed", "idempotency_conflict", "idempotency_in_progress", "service_unavailable", "internal_error"
message string required
type string required: Allowed: "auth", "validation", "quota", "rate_limit", "not_found", "execution", "conflict", "internal"
retryable boolean required
request_id string | null
details object

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "type",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "seoapi_price_pending",
        "seoapi_unavailable",
        "seoapi_busy",
        "seoapi_not_found",
        "seoapi_rate_limited",
        "seoapi_budget_exceeded",
        "seoapi_idempotency_conflict",
        "seoapi_insufficient_credits",
        "seoapi_admission_failed",
        "seoapi_execution_interrupted",
        "seoapi_delivery_unknown",
        "seoapi_response_invalid",
        "seoapi_model_unsupported",
        "seoapi_model_options_invalid",
        "seoapi_provider_rejected",
        "seo_price_pending",
        "seo_provider_blocked",
        "seo_local_rate_limited",
        "seo_fallback_unavailable",
        "seo_fallback_budget_exceeded",
        "seo_pagination_expired",
        "seo_delivery_uncertain",
        "seo_auth_required",
        "seo_initialization_required",
        "seo_permission_denied",
        "seo_verification_required",
        "seo_rate_limited",
        "seo_upstream_unavailable",
        "seo_transport_failed",
        "seo_invalid_response",
        "seo_rpc_error",
        "seo_period_unavailable",
        "seo_account_unavailable",
        "seo_session_busy",
        "seo_configuration_required",
        "validation_error",
        "invalid_request",
        "unsupported_feature",
        "authentication_required",
        "permission_denied",
        "not_found",
        "run_not_found",
        "crawl_not_found",
        "artifact_not_found",
        "session_not_found",
        "profile_not_found",
        "profile_in_use",
        "profile_not_ready",
        "profile_not_cloneable",
        "profile_limit_reached",
        "profile_proxy_conflict",
        "proxy_not_found",
        "proxy_unavailable",
        "invalid_session_options",
        "invalid_query_options",
        "invalid_cursor",
        "idempotency_key_required",
        "browser_session_limit_reached",
        "browser_capacity_exhausted",
        "browser_start_timeout",
        "browser_runtime_unavailable",
        "session_not_active",
        "controller_already_connected",
        "browser_relay_unavailable",
        "precondition_required",
        "precondition_failed",
        "timeout",
        "run_not_ready",
        "artifact_expired",
        "quota_exceeded",
        "insufficient_credits",
        "billing_reconciliation_required",
        "rate_limited",
        "fetch_failed",
        "render_failed",
        "maps_rate_limited",
        "maps_challenge",
        "maps_schema_changed",
        "maps_invalid_response",
        "maps_transport_failed",
        "maps_page_budget_exhausted",
        "google_trends_rate_limited",
        "google_trends_challenge",
        "google_trends_explore_failed",
        "google_trends_widget_missing",
        "google_trends_related_failed",
        "google_trends_invalid_response",
        "google_trends_transport_failed",
        "google_trends_collection_failed",
        "google_ads_account_context_missing",
        "google_ads_batch_failed",
        "google_ads_browser_context_missing",
        "google_ads_browser_unavailable",
        "google_ads_collection_failed",
        "google_ads_page_failed",
        "google_ads_protocol_drift",
        "google_ads_rate_limited",
        "google_ads_timeout",
        "twitter_provider_unavailable",
        "twitter_provider_rejected",
        "twitter_submission_unknown",
        "wechat_transport_failed",
        "wechat_rate_limited",
        "wechat_invalid_response",
        "wechat_redirect_rejected",
        "wechat_verification_required",
        "wechat_parse_failed",
        "blackhatworld_search_failed",
        "blackhatworld_no_results",
        "reddit_read_failed",
        "idempotency_conflict",
        "idempotency_in_progress",
        "service_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "auth",
        "validation",
        "quota",
        "rate_limit",
        "not_found",
        "execution",
        "conflict",
        "internal"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "details": {
      "type": "object",
      "additionalProperties": true
    }
  }
}