---
title: "Create a browser session"
description: "Learn how to create and configure browser sessions in Browsers"
image: "https://help.agent.mq/og.svg"
---

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

# Create a browser session

A browser session represents a single browser instance running in the cloud. It's the fundamental building block of Browsers, providing an isolated environment for your web automation tasks.

## Creating a session

Create browser sessions through the [Sessions API](/browsers/api), which gives you full control over configuration and features. After creation, you'll receive a connection URL to use with your preferred automation framework.

> **Caution**
>
> The create session API is rate limited by the concurrent session limit of your
> plan. Keep the number of live sessions under that limit and back off when a
> request is answered with 429.

### Node.js

```typescript
import { Browsers } from "@agentmq/browsers";

const browsers = new Browsers({ apiKey: process.env.AGENTMQ_TOKEN! });
const session = await browsers.sessions.create({
  // Add configuration options here
});
```

### Python

```python
import os
from agentmq.browsers import Browsers

browsers = Browsers(api_key=os.environ["AGENTMQ_TOKEN"])
session = browsers.sessions.create(
    # Add configuration options here
)
```

### cURL

```bash
curl --request POST \
  --url "https://api.agent.mq/v1/browsers/sessions" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $AGENTMQ_TOKEN" \
  --data '{
    // Add configuration options here
  }'
```

## Configuration options

When creating a session, you can configure various settings. For complete API details, see:

* [Create Session API Reference](/browsers/api)
* Node.js SDK Reference
* Python SDK Reference

### Basic settings

* **Region**: Decrease latency by choosing where your browser runs using browser regions
* **Viewport** - Set custom screen dimensions for your browser window.
* **Keep alive**: Enable [longer-running sessions](/browsers/long-sessions/overview) that run even after disconnection
* **Recording** - Enable/disable [session replay](/browsers/observability/session-replay) (enabled by default)
* **Logging** - Enable/disable session logging for debugging (enabled by default)

### Advanced features

* **Session identity** - Configure browser identity:

  * Automatic fingerprinting (devices, locales, operating systems)
  * Proxy settings
  * Captcha solving (enabled by default)
  * Allowed domains

* **[Extensions](/browsers/core-features/browser-extensions)** - Load custom browser extensions to enhance functionality

* **[Browser Context](/browsers/core-features/contexts)** - Configure isolated browsing contexts for session persistence

* **[User Metadata](/browsers/core-features/session-metadata)** - Attach custom data for session organization and filtering

## Next steps

Once you've created a session, you can:

1. Connect to it using your preferred automation framework - see [Using a browser session](/browsers/getting-started/using-browser-session)
2. Monitor it through the [Session Inspector](/browsers/observability/observability)
3. End it manually or let it timeout - see [Manage a browser session](/browsers/getting-started/manage-browser-session)

## When to use Browsers

Reach for a session when the page requires interaction, the data sits behind a login or client-side JavaScript, or accuracy matters more than speed. A session logs in to portals with a managed identity, navigates complex pages, and extracts the data that a plain HTTP fetch never sees.

Source: https://help.agent.mq/browsers/getting-started/create-browser-session/index.mdx