NextBrowser lets you build and manage browser automation workflows with unparalleled precision, leveraging advanced anti-detection techniques to stay completely stealthy

​
Before the start

​
API key

The first step is a generation of an API key. That can be made in the Settings
Go to Profile → Settings → API Key → Copy your API key
API.gif

​
Security best practices

  • Keep your API key secure and never share it publicly
  • Do not commit API keys to version control
  • Rotate your API keys periodically
  • Use environment variables to store API keys in your applications

​
Error responses

Common authentication-related error responses:
Status CodeDescription
401Unauthorized - Invalid or missing API key
403Forbidden - Valid API key but insufficient permissions
429Too Many Requests - Rate limit exceeded
Example error response: 
{
  "description": "Invalid API key",
  "status_code": 401
}

​
Base URL

All API endpoints are relative to the base URL: 
https://api.example.com/v1
If you want ot create a task, it can be specified the following way: 
url https://app.nextbrowser.com/api/v1/chat/tasks
Learn more about all API endpoints

​
Create a task

Here is an example of the task that will provide a research on the latest news about artificial intelligence and present the summery of the top 3 articles in a bullet format: 
curl --request POST
  --url https://app.nextbrowser.com/api/v1/chat/tasks
  --header 'Authorization: <api-key>'
  --header 'Content-Type: application/json'
  --data '{
  "llm_model": "gemini-2.0-flash",
  "browser_settings": {
    "browser_type": "persistent",
    "os_type": "windows"
  },
  "task_description": "Extract the current price of Bitcoin (BTC)",
  "proxy_settings": {
    "country": "US",
    "region": "California",
    "city": "Canyon country",
    "isp": "Spectrum",
    "proxy_type": "Residential"
  }
}'
Do not forget to add you API key: 
--header "Authorization: x-api-key YOUR_API_KEY"
You will get result in the following format: 
{
  "success": true,
  "payload": {
    "id": "94b8dd65-0988-4b2b-984c-b4ce26c87c2b",
    "chat_session_id": "a9cba3e5-61c8-475e-8df0-41cd1ab23f99",
    "browser_instance_id": "cc619900-a5aa-421d-a18c-2c6193a44077",
    "browser_id": "958faf53",
    "user_id": "<string>",
    "created_at": "2025-06-06T14:21:55.524791Z",
    "state": "processing",
    "task_description": "Extract the current price of Bitcoin (BTC)",
    "llm_model": "gemini-2.0-flash",
    "chat_title": "Extracte the current price of Bitcoin (BTC)"
  },
  "errors": {},
  "description": "Task creation started"
}

​
Get the task status

​
Types of statuses

  • active – the task is ongoing
  • completed – the task is completed
  • failed – an error aquired during the task run

​
GET the task status

After launching the task, it will take some time for the AI agent to process it and prepare the automation result. While waiting, you can check the task’s status as follows: 
curl --request GET
  --url https://app.nextbrowser.com/api/v1/chat/sessions/a9cba3e5-61c8-475e-8df0-41cd1ab23f99/state
  --header 'Authorization: x-api-key'
Add the chat_session_id that you will receive with the responce of task creation request: 
--url https://app.nextbrowser.com/api/v1/chat/sessions/a9cba3e5-61c8-475e-8df0-41cd1ab23f99/state
Do not forget to add you API key: 
--header "Authorization: x-api-key YOUR_API_KEY"
You will get the result in the following format: 
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "user_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "num_tasks": 123,
  "status": "active",
  "browser_instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "browser_id": "<string>",
  "proxy_settings": {},
  "browser_settings": {},
  "tasks": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_at": "2023-11-07T05:31:56Z",
      "finished_at": "2023-11-07T05:31:56Z",
      "done_output": "<string>",
      "structured_output": {},
      "llm_model": "<string>",
      "state": "processing",
      "task_description": "<string>",
      "output_description": "<string>",
      "output_files_path": "<string>",
      "error_message": "<string>",
      "steps": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "created_at": "2023-11-07T05:31:56Z",
          "finished_at": "2023-11-07T05:31:56Z",
          "description": "<string>",
          "status": "pending"
        }
      ]
    }
  ],
  "title": "<string>"
}

​
Task result

​
Types of the output

When using NextBrowser, you can specify the format of the result you want to receive once the automation is complete. This can be:
  • Text
  • Bullet points
  • A table
  • CSV, JSON, PDF, and other document formats
  • PNG, SVG, and other image formats
  • Links

​
Text output

If the task’s status is “completed,” then the response will also include the automation result as the structured output: 
structured_output": {
  	"data": {
    	"description": "Extracted the current price of Bitcoin (BTC)",
    	"content_type": "json",
    	"content": {
      		"json": {
        		"price": "$104,770.88 USD"
      }

​
File output

An example of the file output that can be found indownload_linkssection: 
        "llm_model": "gemini-2.0-flash",
        "state": "completed",
        "task_description": "Extract the current price of Bitcoin (BTC)",
        "output_description": "Complete the task.",
        "output_files_path": null,
        "error_message": null,
        "download_links": [
          "https://nextbrowser-stage-task-output-files.s3.amazonaws.com/users/aa4a16e3-4a76-4541-8536-6a3f8db48267/chats/af28e825-1e33-4f30-97ae-f4e3389ee85e/weather_lisbon_20250606_1406400002.csv?AWSAccessKeyId=AKIA3JQ5JIQQSOKPEVVE&Signature=6z627IX93TebG%2BdYiBLq30m27wM%3D&Expires=1749222412"
        ],

​
How to describe the result format

The more precisely you describe the format and structure of the result you want to receive, the more accurate the automation output will be Bad example of output prompting 
Collect data on the top 10 sneakers from Amazon and create a CSV
Good example of output prompting 
Collect data on the top 10 sneakers from Amazon and create a CSV that contains: the export date, ranking position, product name, price, and product link