Make your first API request

You need a BrowserBunny account, an API key, and an available test target. Manage your keys in the dashboard.

Connect to the API

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

export BROWSERBUNNY_API_KEY="YOUR_API_KEY"

Retrieve the device catalog:

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.

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.

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.

Follow the run

Replace RUN_ID with the returned run ID:

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:

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.

​Connect to the API

​Submit a test

​Follow the run

Connect to the API

Submit a test

Follow the run