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

# Open a session

> Open a cloud browser session. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing.

## Price

$0.06 per hour open, $0.84 per hour once a prompt has run, billed when it closes, one minute at least. Traffic adds $5 per GB through the managed network location, the default, and $0.20 per GB direct or through your own proxy.

See [Pricing](https://docs.stophy.dev/account/pricing.md).

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/browser \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl":300,"activityTtl":60,"recording":true,"metadata":{"purpose":"docs-example"}}'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/browser", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ttl: 300,
    activityTtl: 60,
    recording: true,
    metadata: { purpose: "docs-example" },
  }),
});
console.log(await response.json());
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/browser",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "ttl": 300,
        "activityTtl": 60,
        "recording": True,
        "metadata": {"purpose": "docs-example"},
    },
)
print(response.json())
```

```json 200 theme={null}
{
  "success": true,
  "id": "6bd8981c-f2a8-403c-b188-352828c08bc2",
  "status": "active",
  "createdAt": "2026-11-17T17:50:55.511Z",
  "startedAt": "2026-11-17T17:50:55.511Z",
  "finishedAt": null,
  "timeoutAt": "2026-11-17T17:51:55.511Z",
  "lastActivity": "2026-11-17T17:50:55.511Z",
  "expiresAt": "2026-11-17T17:55:55.505Z",
  "metadata": {
    "purpose": "docs-example"
  },
  "networkPolicyId": null,
  "networkPolicyVersion": null,
  "extensions": [],
  "proxyUsedMb": null,
  "browserCredits": null,
  "browserCostUsd": null,
  "proxyCredits": null,
  "proxyCostUsd": null,
  "cdpUrl": "<cdpUrl>",
  "liveViewUrl": "<liveViewUrl>",
  "interactiveLiveViewUrl": "<interactiveLiveViewUrl>",
  "streamWebView": true,
  "recordingStatus": "recording",
  "recordingAvailable": true,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "7f65952e-73c2-41ac-a9cf-dc429ba915e1"
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/browser
openapi: 3.1.0
info:
  title: Stophy API
  version: '1'
  description: >-
    Each operation shows its method and its input: a JSON object body, path and
    query parameters, or a file upload.


    Responses leave out empty values: null, empty strings, empty objects and
    empty nested lists are not sent.


    Text comes back whole. To get shorter responses, add
    ?maxTextLength=<characters> to the URL. Every text value longer than that is
    cut and ends with …. A screenshot is never cut, and a page whose text was
    cut has isTruncated set to true.


    x-cost-usd is what one call costs, in dollars. Every call costs the same,
    whatever it returns, unless an operation's description says it costs per 10
    results, or per hour of audio. Then x-cost-usd is the lowest price and
    x-cost-usd-max the most one call can cost. Where an operation takes limit,
    send it to return fewer results and pay for fewer.


    When a response has a cursor, send it back unchanged with the same input to
    get the next page. When it has a page, send the next page number.
servers:
  - url: https://api.stophy.dev
security:
  - apiKey: []
paths:
  /v1/browser:
    post:
      summary: Open a cloud browser session.
      description: >-
        $0.06 per hour open, $0.84 per hour once a prompt has run, billed when
        it closes, one minute at least. Traffic adds $5 per GB on the default
        network, and $0.20 per GB direct or through your own proxy. ttl is the
        most it can live, activityTtl how long it waits with no call before it
        closes.
      operationId: browserCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ttl:
                  default: 600
                  type: integer
                  minimum: 30
                  maximum: 21600
                activityTtl:
                  default: 300
                  type: integer
                  minimum: 10
                  maximum: 21600
                streamWebView:
                  type: boolean
                zeroDataRetention:
                  type: boolean
                blockAds:
                  type: boolean
                solveCaptchas:
                  type: boolean
                captureConsole:
                  type: boolean
                screen:
                  description: >-
                    Window size in pixels, width 500 to 6144 and height 320 to
                    3456, the sizes Chrome keeps. Sites still read a 1920x1080
                    display. Leave it out unless you need it.
                  type: object
                  properties:
                    width:
                      type: integer
                      minimum: 500
                      maximum: 6144
                    height:
                      type: integer
                      minimum: 320
                      maximum: 3456
                  required:
                    - width
                    - height
                  additionalProperties: false
                allowResizing:
                  description: >-
                    false keeps the window at its size: setViewportSize and CDP
                    resize commands are accepted and change nothing. Leave it
                    out to allow resizing.
                  type: boolean
                pdfRenderer:
                  description: >-
                    true shows PDFs in the browser's own viewer. Left out or
                    false, a PDF is saved as a download.
                  type: boolean
                recording:
                  description: >-
                    true records every tab the session shows as an MP4 video.
                    Free. The video is made after the session stops and kept 7
                    days. Read recordingStatus on the session, then
                    recordingUrl. Not with zeroDataRetention.
                  type: boolean
                metadata:
                  description: >-
                    Up to 10 pairs of text, keys up to 100 characters and values
                    up to 1000. Sent back with the session, and list can filter
                    on them.
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: string
                    maxLength: 1000
                extensionIds:
                  description: >-
                    Up to 3 ids of extensions you uploaded with POST
                    /v1/browser/extensions. They load before the first page
                    opens and cannot change while the session runs. Leave it out
                    for a plain browser: loading an extension changes what sites
                    can see.
                  maxItems: 3
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                allowedDomains:
                  maxItems: 100
                  type: array
                  items:
                    type: string
                    pattern: >-
                      ^(?:\*\.)?[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$
                networkPolicyId:
                  description: >-
                    A saved network policy from POST
                    /v1/browser/network-policies. Its rules apply to every
                    request the session makes, and a change to the policy
                    reaches the running session within seconds. Not with
                    allowedDomains.
                  type: string
                  minLength: 1
                  maxLength: 100
                proxy:
                  description: >-
                    residential is the default network, and the only one
                    location.country applies to. direct uses no proxy. Or send
                    your own proxy URL.
                  anyOf:
                    - type: string
                      const: residential
                    - type: string
                      const: direct
                    - type: string
                profile:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 200
                    saveChanges:
                      default: true
                      type: boolean
                  required:
                    - name
                  additionalProperties: false
                location:
                  type: object
                  properties:
                    country:
                      type: string
                  additionalProperties: false
      responses:
        '200':
          description: The session.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - costUsd
                  - creditsUsed
                  - requestId
                properties:
                  success:
                    const: true
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - active
                      - destroyed
                  createdAt:
                    type: string
                    format: date-time
                  startedAt:
                    type: string
                    format: date-time
                    description: When the session opened.
                  finishedAt:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: When the session ended. Null while it runs.
                  timeoutAt:
                    type: string
                    format: date-time
                    description: >-
                      When the session stops by itself if nothing else happens:
                      the earlier of expiresAt and the idle limit after the last
                      call, which moves forward with each call. After the
                      session ends it is finishedAt.
                  lastActivity:
                    type: string
                    format: date-time
                  expiresAt:
                    type: string
                    format: date-time
                  metadata:
                    type: object
                    additionalProperties:
                      type: string
                    description: The pairs sent when the session opened.
                  networkPolicyId:
                    type:
                      - string
                      - 'null'
                    description: >-
                      The network policy the session was opened with. Null for
                      none.
                  networkPolicyVersion:
                    type:
                      - integer
                      - 'null'
                    description: >-
                      The version of that policy the session enforces now. It
                      goes up when a change to the policy reaches the session,
                      so a session behind the policy's version has not received
                      the change yet.
                  proxyUsedMb:
                    type:
                      - number
                      - 'null'
                    description: >-
                      Traffic through all networks, in MB. Null until the
                      session closes.
                  browserCredits:
                    type:
                      - integer
                      - 'null'
                    description: >-
                      Older field: the browser time in $0.002 steps. Null until
                      the session closes.
                  browserCostUsd:
                    type:
                      - number
                      - 'null'
                    description: >-
                      What the time the session was open cost, in dollars. Null
                      until it closes.
                  proxyCredits:
                    type:
                      - integer
                      - 'null'
                    description: >-
                      Older field: the traffic in $0.002 steps. Null until the
                      session closes.
                  proxyCostUsd:
                    type:
                      - number
                      - 'null'
                    description: >-
                      What the traffic cost, in dollars. Null until the session
                      closes.
                  cdpUrl:
                    type: string
                    description: Connect a CDP client such as Playwright here.
                  liveViewUrl:
                    type: string
                    description: Watch the session. Sent with streamWebView.
                  interactiveLiveViewUrl:
                    type: string
                    description: Watch and control the session. Sent with streamWebView.
                  streamWebView:
                    type: boolean
                  extensions:
                    type: array
                    description: >-
                      The extensions loaded in the session, in the order of
                      extensionIds.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        runtimeId:
                          type: string
                          description: >-
                            Chrome's id for it, as in
                            chrome-extension://{runtimeId}/.
                        version:
                          type: string
                  recordingStatus:
                    type: string
                    enum:
                      - none
                      - recording
                      - processing
                      - ready
                      - failed
                    description: >-
                      none: the session was not recorded, or its video was
                      deleted. recording: the session is running. processing:
                      the session stopped and the video is being made, usually
                      within a few minutes, or the status could not be read yet,
                      so read it again. ready: recordingUrl works. failed: the
                      video was never made and cannot be any more. A ready video
                      is kept 7 days.
                  recordingAvailable:
                    type: boolean
                    description: >-
                      false when recordingStatus is none or failed, true while a
                      video is or will be there.
                  recordingTruncated:
                    type: boolean
                    description: >-
                      true when the video ends early because the session showed
                      more than a recording can hold.
                  recordingUrl:
                    type: string
                    description: >-
                      The MP4, with no key needed, for 15 minutes. It plays and
                      seeks in a browser or player. Sent when recordingStatus is
                      ready. Read the session again for a new link.
                  warning:
                    type: string
                  creditsUsed:
                    type: integer
                  costUsd:
                    type: number
                    description: What this call cost, in dollars.
                  requestId:
                    type: string
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
components:
  headers:
    RequestId:
      description: The request id. Quote it when you report a problem.
      schema:
        type: string
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Unix time in seconds when the current window resets.
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    Error:
      description: The request failed. Retry-After says when trying again can help.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
        - success
        - error
        - code
      properties:
        success:
          const: false
        error:
          type: string
          description: What went wrong and what to do next.
        code:
          type: string
          enum:
            - apiKeyRequired
            - busy
            - checkRunning
            - cliSessionCompleted
            - cliSessionExists
            - cliSessionNotFound
            - forbidden
            - freeLimit
            - insufficientCredits
            - internalError
            - inviteClaimed
            - inviteDisabled
            - inviteExpired
            - inviteUsedUp
            - invalidCliSession
            - invalidCliVerifier
            - invalidRequest
            - jobFinished
            - methodNotAllowed
            - notFound
            - payloadTooLarge
            - profileBusy
            - profileTooLarge
            - prohibitedPermission
            - promptInjectionDetected
            - rateLimited
            - sourceChanged
            - sourceRefused
            - siteNotRead
            - sourceTimeout
            - sourceUnavailable
            - unauthorized
            - unsupportedMediaType
        retryable:
          type: boolean
          description: true when trying again can help.
        retryAfterSeconds:
          type: integer
        requestId:
          type: string
        requiredCredits:
          type: number
          description: >-
            Older field: the most the call can cost, in $0.002 steps. Sent when
            the balance is too low.
        availableCredits:
          type: number
          description: 'Older field: the balance in $0.002 steps. Sent with requiredCredits.'
        requiredUsd:
          type: number
          description: >-
            The most the call can cost, in dollars. Sent when the balance is too
            low.
        availableUsd:
          type: number
          description: What is left on the account, in dollars. Sent with requiredUsd.
        billingUrl:
          type: string
          description: Where to add money. Sent with requiredUsd.
        signupUrl:
          type: string
          const: https://stophy.dev/signup
          description: >-
            Where a person gets a key. Sent with apiKeyRequired, freeLimit and
            an invalid key.
        signup:
          type: string
          const: POST https://api.stophy.dev/v1/signup
          description: >-
            The call that gets an agent a key with no human. Sent next to
            signupUrl.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.