Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Session management (HTTP)

Use the HTTP API to manage browser sessions and tabs without using WebSocket connections. This is useful for session lifecycle operations like creating sessions, listing tabs, and cleaning up resources.

Before you begin, make sure you create a custom API Token with the Browser Rendering - Edit permission. For more information, refer to REST API — Before you begin.

The API reference documents all session management endpoints under /devtools.

Step 1: Acquire a browser session

Create a new browser session using the POST /devtools/browser endpoint. The session will remain active for the specified keep-alive time (in this example, 10 minutes).

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-rendering/devtools/browser?keep_alive=600000" \
  --request POST \
  --header "Authorization: Bearer {api_token}"
{
  "sessionId": "1909cef7-23e8-4394-bc31-27404bf4348f",
  "webSocketDebuggerUrl": "wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/devtools/browser/1909cef7-23e8-4394-bc31-27404bf4348f"
}

Save the sessionId from the response. You will use it in subsequent requests.

Step 2: Create a tab with a specific URL

Open a new tab in your browser session and navigate to a specific URL using the PUT /devtools/browser/{session_id}/json/new endpoint.

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-rendering/devtools/browser/SESSION_ID/json/new?url=https%3A%2F%2Fexample.com" \
  --request PUT \
  --header "Authorization: Bearer {api_token}"
{
  "id": "8E598E996530FB09E46A22B8B7754F7F",
  "type": "page",
  "url": "https://example.com",
  "title": "Example Domain",
  "description": "",
  "devtoolsFrontendUrl": "https://live.browser.run/ui/view?wss=live.browser.run/api/devtools/browser/1909cef7-23e8-4394-bc31-27404bf4348f/page/8E598E996530FB09E46A22B8B7754F7F?jwt=...",
  "webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/1909cef7-23e8-4394-bc31-27404bf4348f/page/8E598E996530FB09E46A22B8B7754F7F?jwt=..."
}

Step 3: List all targets

List all targets (tabs) in your session to verify the tab was created and get the devtoolsFrontendUrl.

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-rendering/devtools/browser/SESSION_ID/json/list" \
  --request GET \
  --header "Authorization: Bearer {api_token}"
[
  {
    "id": "8E598E996530FB09E46A22B8B7754F7F",
    "type": "page",
    "url": "https://example.com",
    "title": "Example Domain",
    "description": "",
    "devtoolsFrontendUrl": "https://live.browser.run/ui/view?wss=live.browser.run/api/devtools/browser/1909cef7-23e8-4394-bc31-27404bf4348f/page/8E598E996530FB09E46A22B8B7754F7F?jwt=...",
    "webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/1909cef7-23e8-4394-bc31-27404bf4348f/page/8E598E996530FB09E46A22B8B7754F7F?jwt=..."
  }
]

Step 4: Open the DevTools UI

Copy the devtoolsFrontendUrl from the response and open it in Chrome. This URL provides direct access to the Chrome DevTools UI connected to your remote browser session.

Once opened, the DevTools UI will load and you can:

  • Inspect the DOM and CSS
  • Debug JavaScript with breakpoints
  • Monitor network requests
  • View console messages
  • Execute JavaScript in the console
  • Navigate to different URLs

Step 5: Clean up

When you are done, close the browser session to release resources.

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-rendering/devtools/browser/SESSION_ID" \
  --request DELETE \
  --header "Authorization: Bearer {api_token}"
{
  "status": "closing"
}

Troubleshooting

If you have questions or encounter an error, see the Browser Rendering FAQ and troubleshooting guide.