List Browser Sessions

GET/v1/browser/sessions

Lists Team-scoped Browser Sessions. The default filter is active; use status=all for retained stopped history. Runtime node, provider profile ID, and raw CDP endpoints are never returned.

On this page

Request example

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

API base https://kieapi.com

curl -G "https://kieapi.com/v1/browser/sessions" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  --data-urlencode 'limit=50'

Authentication

BearerAuth

Parameters

status query · array of string

Repeat for multiple lifecycle states, or use all by itself.

profile_id query · string

created_from query · string (date-time)

created_to query · string (date-time)

limit query · integer

Default: 50

Minimum: 1

Maximum: 100

cursor query · string

Responses

200 Browser sessions.

application/json

BrowserSessionsResponse

items array of BrowserSession required
next_cursor string | null required

400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

403 Authenticated principal cannot access this resource.

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

Schemas

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

BrowserSessionsResponse

object

items array of BrowserSession required
next_cursor string | null required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "items",
    "next_cursor"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BrowserSession"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

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
}

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"
}

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
    }
  }
}