---
title: "Create a browser session"
description: "Create a browser session."
---

> Documentation Index
> Fetch the complete documentation index at: https://help.tooluse.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a browser session

<p>Store an application Agent key in <code>TOOLUSE_API_KEY</code>. Session creation is a write and may incur browser usage; choose a bounded timeout and release the session when done.</p>
<pre><code class="language-bash">curl -X POST "https://api.tooluse.net/v1/browsers/sessions" \
  -H "Authorization: Bearer $TOOLUSE_API_KEY" \
  -H "Idempotency-Key: tooluse-example-001" \
  -H "Content-Type: application/json" \
  -d '{"timeout":300,"browserSettings":{"viewport":{"width":1280,"height":720}}}'
</code></pre>
<p>The response contains <code>id</code>, status, connection URLs and session properties. Save <code>id</code> as <code>SESSION_ID</code>. Reuse the exact idempotency key and request body to reconcile the same create; changed input under that key returns a conflict. A new intended session needs a new key. The default timeout is 3600 seconds; accepted values are 60 through 21600 seconds.</p>
<p>Capacity refusal returns <code>429</code>; insufficient platform credit returns <code>402</code>. Read the response before deciding what to do next.</p>
<pre><code class="language-bash">curl -X POST "https://api.tooluse.net/v1/browsers/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOOLUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"REQUEST_RELEASE"}'
</code></pre>

Source: https://help.tooluse.net/browsers/getting-started/create-browser-session/index.mdx