> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfsky.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Start profile

> Start a saved profile and restore its enabled storage types. Omitted proxy settings retain the stored proxy; explicit overrides apply to this run. Starting an already running profile can return its existing session. Use the returned connection fields as-is.



## OpenAPI

````yaml /api-reference/openapi.json post /profiles/{profile_uuid}/start
openapi: 3.1.0
info:
  title: Surfsky API
  version: 0.1.0
  description: >-
    Start cloud browsers, control them through CDP, and manage the profiles,
    proxies, and fingerprints they run with.
servers:
  - url: '{baseUrl}'
    variables:
      baseUrl:
        default: https://YOUR_API_HOST
        description: API base URL from your Surfsky dashboard, including https://.
security:
  - ApiToken: []
tags:
  - name: profiles
    description: >-
      Start, stop, and manage browsers. A one-time profile is discarded when it
      stops; a persistent profile keeps its cookies, storage, and fingerprint
      according to its storage settings.
  - name: proxies
    description: >-
      Look up what the premium and shared pools can offer before you pin a
      location, and read your traffic quota.
  - name: fingerprints
    description: >-
      The value sets a fingerprint field accepts. Use these to pin a renderer,
      screen, or device model instead of guessing at a string.
  - name: extensions
    description: Upload Chrome extensions once and load them into any browser you start.
  - name: captcha
    description: Balance on the CAPTCHA solver behind your account.
paths:
  /profiles/{profile_uuid}/start:
    post:
      tags:
        - profiles
      summary: Start profile
      description: >-
        Start a saved profile and restore its enabled storage types. Omitted
        proxy settings retain the stored proxy; explicit overrides apply to this
        run. Starting an already running profile can return its existing
        session. Use the returned connection fields as-is.
      operationId: start_profile_profiles__profile_uuid__start_post
      parameters:
        - name: profile_uuid
          in: path
          required: true
          schema:
            type: string
            minLength: 32
            maxLength: 32
            title: Profile Uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartStatefulProfileIn'
            example: {}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStarted'
              example:
                success: true
                internal_uuid: a8fb62f90611456aa75422b01c385a62
                ws_url: wss://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62
                inspector:
                  list: >-
                    https://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62/inspector
                  pages: []
                  screencast: >-
                    wss://YOUR_API_HOST/screencast/a8fb62f90611456aa75422b01c385a62/devtools/page/PAGE_ID
        '401':
          description: Missing or invalid API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Account or feature access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Request, browser, session, or traffic limit reached; inspect code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    StartStatefulProfileIn:
      properties:
        proxy_blacklist:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Proxy Blacklist
        domain_routes:
          anyOf:
            - items:
                $ref: '#/components/schemas/DomainRouteConfig'
              type: array
            - type: 'null'
          title: Domain Routes
        proxy:
          anyOf:
            - type: string
              minLength: 1
              format: uri
            - $ref: '#/components/schemas/ProxyConfig'
          title: Proxy
          description: >-
            Proxy URL or pool selection. Choose tier explicitly to require
            shared or premium. See the [proxy guide](/proxies) for targeting
            rules.
        open_vpn:
          $ref: '#/components/schemas/OpenVPNConfig'
        wireguard:
          $ref: '#/components/schemas/WireGuardConfig'
        anti_captcha:
          $ref: '#/components/schemas/AntiCaptchaIn'
        enable_chromedriver:
          type: boolean
          title: Enable Chromedriver
          default: false
        extensions:
          items:
            type: string
          type: array
          maxItems: 5
          title: Extensions
        browser_settings:
          $ref: '#/components/schemas/BrowserSettings'
      additionalProperties: false
      type: object
      title: StartStatefulProfileIn
    SessionStarted:
      type: object
      properties:
        success:
          type: boolean
          const: true
        internal_uuid:
          type: string
          description: >-
            Identifier to use for stop, scrape, and live connections. May equal
            profile_uuid.
        ws_url:
          type: string
          description: Live CDP connection URL. Keep private.
        inspector:
          type: object
          properties:
            list:
              type: string
            pages:
              type: array
              items:
                type: object
                properties:
                  page_url:
                    type: string
                  devtools_url:
                    type: string
            screencast:
              type: string
          required:
            - list
            - pages
            - screencast
      required:
        - success
        - internal_uuid
        - ws_url
        - inspector
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        msg:
          type: string
        code:
          type: string
        data: {}
        detail: {}
        error: {}
      description: >-
        Error fields vary for forwarded responses. Check HTTP status and code
        when present.
    DomainRouteConfig:
      properties:
        proxy:
          type: string
          minLength: 1
          format: uri
          title: Proxy
        domain:
          items:
            type: string
          type: array
          title: Domain
        domain_suffix:
          items:
            type: string
          type: array
          title: Domain Suffix
        domain_keyword:
          items:
            type: string
          type: array
          title: Domain Keyword
        domain_regex:
          items:
            type: string
          type: array
          title: Domain Regex
      type: object
      required:
        - proxy
      title: DomainRouteConfig
      description: >-
        Route specific domains through a different proxy.


        - domain: exact domain match (e.g., ["google.com"])

        - domain_suffix: suffix match (e.g., [".google.com"] matches
        *.google.com)

        - domain_keyword: keyword match (e.g., ["google"] matches any domain
        containing "google")

        - domain_regex: regex match (e.g., ["^stun\\..+"] matches
        stun.example.com)
    ProxyConfig:
      properties:
        tier:
          anyOf:
            - $ref: '#/components/schemas/ProxyTier'
            - type: 'null'
        type:
          anyOf:
            - $ref: '#/components/schemas/ProxyType'
            - type: 'null'
        country:
          anyOf:
            - type: string
              pattern: ^[A-Za-z]{2}$
            - type: 'null'
          title: Country
        region:
          anyOf:
            - type: string
              pattern: ^[\w \-]{1,64}$
            - type: 'null'
          title: Region
        city:
          anyOf:
            - type: string
              pattern: ^[\w \-]{1,64}$
            - type: 'null'
          title: City
        pool:
          anyOf:
            - $ref: '#/components/schemas/RegionalPool'
            - type: 'null'
        asn:
          anyOf:
            - type: integer
              maximum: 4294967295
              minimum: 1
            - type: 'null'
          title: Asn
        lat:
          anyOf:
            - type: number
              maximum: 90
              minimum: -90
            - type: 'null'
          title: Lat
        lon:
          anyOf:
            - type: number
              maximum: 180
              minimum: -180
            - type: 'null'
          title: Lon
        session_minutes:
          anyOf:
            - type: integer
              maximum: 10080
              minimum: 1
            - type: 'null'
          title: Session Minutes
        unique_ip:
          type: boolean
          title: Unique Ip
          default: false
        keep_asn:
          type: boolean
          title: Keep Asn
          default: false
        keep_ip:
          type: boolean
          title: Keep Ip
          default: false
      additionalProperties: false
      type: object
      title: ProxyConfig
    OpenVPNConfig:
      properties:
        config:
          type: string
          title: Config
        username:
          type: string
          title: Username
          default: ''
        password:
          type: string
          title: Password
          default: ''
      type: object
      required:
        - config
      title: OpenVPNConfig
    WireGuardConfig:
      properties:
        private_key:
          type: string
          title: Private Key
        address:
          items:
            type: string
          type: array
          title: Address
        peers:
          items:
            $ref: '#/components/schemas/WireGuardPeerConfig'
          type: array
          title: Peers
        mtu:
          type: integer
          title: Mtu
          default: 1408
      type: object
      required:
        - private_key
        - address
        - peers
      title: WireGuardConfig
    AntiCaptchaIn:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        gemini_api_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Gemini Api Key
        disable_external_providers:
          type: boolean
          title: Disable External Providers
          default: false
        external_providers_initially_enabled:
          type: boolean
          title: External Providers Initially Enabled
          default: true
        auto_captcha_types:
          items:
            type: string
          type: array
          title: Auto Captcha Types
          default:
            - recaptcha
            - hcaptcha
            - geetest
            - turnstile
            - bls
            - perimeterx
            - datadome
            - datadome_audio
      type: object
      title: AntiCaptchaIn
    BrowserSettings:
      properties:
        inactive_kill_timeout:
          type: integer
          maximum: 3600
          minimum: 1
          title: Inactive Kill Timeout
          default: 30
          description: >-
            Seconds without browser activity before automatic stop. An idle
            WebSocket alone does not keep the session active.
        cache_enabled:
          type: boolean
          title: Cache Enabled
          default: false
        cache_key:
          anyOf:
            - type: string
              maxLength: 255
              pattern: ^[A-Za-z0-9_-][A-Za-z0-9._-]*$
            - type: 'null'
          title: Cache Key
          description: >-
            Required when cache_enabled is true. See [shared
            cache](/shared-cache) for sharing behavior.
      type: object
      title: BrowserSettings
    ProxyTier:
      type: string
      enum:
        - shared
        - premium
      title: ProxyTier
    ProxyType:
      type: string
      enum:
        - residential
        - mobile
      title: ProxyType
    RegionalPool:
      type: string
      enum:
        - western
        - europe
        - westeurope
        - northamerica
        - southamerica
        - asia
        - centralasia
        - southasia
        - eastasia
        - sea
        - oceania
        - mena
        - middleeast
        - africa
        - northafrica
        - westafrica
        - eastafrica
        - centralafrica
        - southernafrica
      title: RegionalPool
    WireGuardPeerConfig:
      properties:
        public_key:
          type: string
          title: Public Key
        endpoint:
          type: string
          title: Endpoint
        allowed_ips:
          items:
            type: string
          type: array
          title: Allowed Ips
        pre_shared_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Shared Key
        persistent_keepalive_interval:
          anyOf:
            - type: integer
            - type: 'null'
          title: Persistent Keepalive Interval
        reserved:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Reserved
      type: object
      required:
        - public_key
        - endpoint
      title: WireGuardPeerConfig
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: X-Cloud-Api-Token
      description: API token from your dashboard.

````