> Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

---
title: Sessions
"og:image": "https://libretto.sh/docs/og/libretto-cloud-api/sessions.png"
---

> Use the sessions API to create, inspect, and close hosted browser sessions directly.

All routes on this page require `x-api-key`.

### POST `/v1/sessions/create`

Start a hosted browser session.

Request fields:

* `timeout_seconds`: optional session timeout, default `3600`, max `7200`
* `start_url`: optional URL opened before CDP is returned
* `gpu`: optional boolean GPU request
* `viewport`: optional `{ width, height }` viewport
* `headless`: optional boolean browser mode
* `residential_proxy`: optional residential proxy location object

Prefer `start_url` over navigating with Playwright immediately after connect. Use `residential_proxy` for location-sensitive sessions that need traffic to originate from a specific residential proxy country, US state, city, ZIP code, or ASN. See [Residential proxy locations](/libretto-cloud-hosting/stealth#residential-proxy-locations) for the supported fields and combination rules.

Response fields:

* `success`
* `session_id`
* `status`
* `cdp_url`
* `live_view_url`

Example:

```bash
curl -X POST "https://api.libretto.sh/v1/sessions/create" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "timeout_seconds": 1800
    }
  }'
```

### POST `/v1/sessions/get`

Inspect a hosted browser session.

Request fields:

* `session_id`: session id returned from `sessions/create`

Response fields:

* `session_id`
* `status`
* `cdp_url`
* `live_view_url`

Use this route when `sessions/create` returned a queued or starting session and you need to poll for the CDP URL or live view URL.

### POST `/v1/sessions/close`

Close a hosted browser session by session id.

Request fields:

* `session_id`: session id returned from `sessions/create`

Response fields:

* `success`
* `message`

Example:

```bash
curl -X POST "https://api.libretto.sh/v1/sessions/close" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "session_id": "<session-id>"
    }
  }'
```

<CardGroup cols={3}>
  <Card title="Libretto Cloud API overview" icon="book-open" href="/libretto-cloud-api/overview">
    See the shared request format.
  </Card>

  <Card title="Jobs and Logs" icon="terminal" href="/libretto-cloud-api/jobs-and-logs">
    Run workflows and inspect results.
  </Card>

  <Card title="Recordings" icon="video" href="/libretto-cloud-api/recordings">
    Generate recording URLs for jobs and browser sessions.
  </Card>

  <Card title="Deployments and Workflows" icon="rocket" href="/libretto-cloud-api/deployments-and-workflows">
    Deploy workflows before invoking them.
  </Card>
</CardGroup>