> ## 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.

# List sessions

> List your browser sessions. Send one request and get JSON back. Examples in cURL, TypeScript and Python. A failed call costs nothing.

## Price

Free.

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

```bash cURL theme={null}
curl https://api.stophy.dev/v1/browser \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/browser", {
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
  },
});
console.log(await response.json());
```

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

import requests

response = requests.get(
    "https://api.stophy.dev/v1/browser",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
print(response.json())
```

```json 200 theme={null}
{
  "success": true,
  "sessions": [
    {
      "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
    }
  ],
  "nextCursor": null,
  "hasMore": false,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "30c200ad-1f60-49a1-bbd7-19182239a4da"
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /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:
    get:
      summary: List your browser sessions.
      description: >-
        Free. Newest first. Send nextCursor as cursor to get the next page.
        metadata is key to match any value, or key=value to match one, and
        sending it again narrows the list further.
      operationId: browserList
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - active
              - destroyed
        - name: metadata
          in: query
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            maxItems: 10
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Your sessions.
          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
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        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
                  nextCursor:
                    type:
                      - string
                      - 'null'
                  hasMore:
                    type: boolean
                  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.