> ## Documentation Index
> Fetch the complete documentation index at: https://browserbunny.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Make your first API request

> Connect to BrowserBunny and submit a browser test.

You need a BrowserBunny account, an API key, and an available test target.
Manage your keys in the [dashboard](https://dash.browserbunny.dev).

## Connect to the API

Keep your API key in an environment variable. Send it in the `Authorization`
header with the `Bearer` prefix.

```bash theme={null}
export BROWSERBUNNY_API_KEY="YOUR_API_KEY"
```

Retrieve the device catalog:

```bash theme={null}
curl --fail-with-body https://api.browserbunny.dev/v1/devices \
  -H "Authorization: Bearer $BROWSERBUNNY_API_KEY"
```

Choose a device from the response whose `enabled` value is `true` and whose
`locked` value is `false`. Use its `id` in your run request.

## Submit a test

Replace `DEVICE_ID` with your chosen device ID and set `start_url` to a site you
are authorized to test. Describe the task in `test_task`.

```bash theme={null}
curl --fail-with-body https://api.browserbunny.dev/v1/runs \
  -H "Authorization: Bearer $BROWSERBUNNY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-homepage-test-001" \
  --data '{
    "start_url": "https://example.com",
    "test_task": "Verify that the homepage loads and has a page title.",
    "devices": ["DEVICE_ID"]
  }'
```

A new run returns HTTP `202`. Save the `id` from the response to retrieve its
progress. Creating a run starts test execution and can consume account usage.

<Note>
  Keep the same idempotency key and request body when retrying an uncertain
  submission. Use a new key for a new test. Reusing a key with a changed request
  returns HTTP `409`.
</Note>

## Follow the run

Replace `RUN_ID` with the returned run ID:

```bash theme={null}
curl --fail-with-body https://api.browserbunny.dev/v1/runs/RUN_ID \
  -H "Authorization: Bearer $BROWSERBUNNY_API_KEY"
```

The run's `status` describes execution progress; `outcome` describes its result.
A finished run has `status: "complete"`. Open the returned `run_url` while signed
in to the owning account to review the run in your dashboard.

Retrieve a page of logs:

```bash theme={null}
curl --fail-with-body 'https://api.browserbunny.dev/v1/runs/RUN_ID/logs?limit=200' \
  -H "Authorization: Bearer $BROWSERBUNNY_API_KEY"
```

If the response includes `next_cursor`, pass that value unchanged as the `cursor`
query parameter to retrieve the next page.