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

# Browser

> Execute browser automation tasks: navigate pages, extract data, fill forms, interact with websites

## Overview

Your agent tells the Browser API what to do in plain English. It navigates pages, pulls structured data, fills out forms, clicks buttons, and runs multi-step workflows on your behalf.

You get a cost estimate before paying.

## Authentication

Requires x402 payment. First call analyzes the task and returns a quote (402), second call with payment executes asynchronously.

## Request Body

<ParamField body="task" type="string" required>
  Natural language description of the browser task (minimum 10 characters, max 50,000).

  Examples:

  * "Go to example.com/pricing and extract all plan names, prices, and features into a table"
  * "Navigate to the contact page and fill out the form with our company info"
  * "Search for 'AI startups' on ProductHunt and extract the top 10 results"
</ParamField>

<ParamField body="output_schema" type="object">
  JSON schema for the expected output. If you pass this, the browser extracts data matching your schema.

  ```json theme={null}
  {
    "products": [{
      "name": "string",
      "price": "number",
      "features": ["string"]
    }]
  }
  ```
</ParamField>

<ParamField body="start_url" type="string">
  Starting URL for the browser task. If omitted, the agent decides where to begin based on the task description.
</ParamField>

<ParamField body="allowed_domains" type="string[]">
  Restrict browsing to specific domains. The agent will not navigate outside these domains.
</ParamField>

<ParamField body="profile_id" type="string">
  Persistent browser profile ID. Reuses cookies, local storage, and session state across tasks. Create profiles via `POST /v1/tools/browser/profiles`.
</ParamField>

<ParamField body="secrets" type="object">
  Domain-scoped credentials for authenticated browsing. Keys are domains, values are credential strings.

  ```json theme={null}
  {
    "github.com": "username:token",
    "dashboard.stripe.com": "sk_live_xxx"
  }
  ```

  Secrets are passed securely to the browser agent and used for authentication on matching domains.
</ParamField>

<ParamField body="session_id" type="string">
  UUID to resume a previous browser session (preserves cookies, login state).
</ParamField>

<ParamField body="max_steps" type="integer">
  Maximum number of browser steps (1-100). Defaults to the environment maximum. Lower values reduce cost.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Quote Response (402)

The first request analyzes the task and returns a cost estimate:

<ResponseField name="context.quote_id" type="string">
  Quote ID to include in payment request
</ResponseField>

<ResponseField name="context.task_summary" type="string">
  Summary of what the browser will do
</ResponseField>

<ResponseField name="context.estimated_steps" type="integer">
  Estimated number of browser steps needed
</ResponseField>

<ResponseField name="context.max_steps" type="integer">
  Maximum steps allowed for this task
</ResponseField>

<ResponseField name="context.estimated_cost" type="string">
  Total estimated cost in USDC
</ResponseField>

<ResponseField name="context.complexity_score" type="number">
  Task complexity score (0-1)
</ResponseField>

<ResponseField name="context.expires_at" type="string">
  Quote expiration timestamp (30 minutes)
</ResponseField>

## Execution Response (202)

After payment, the browser task runs asynchronously:

<ResponseField name="request_id" type="string">
  Job ID for polling status at `/v1/requests/{id}`
</ResponseField>

<ResponseField name="status" type="string">
  `processing` while the browser task runs
</ResponseField>

<ResponseField name="browser.estimated_steps" type="integer">
  Estimated steps from the quote
</ResponseField>

<ResponseField name="browser.estimated_cost" type="string">
  Estimated cost from the quote
</ResponseField>

## Completed Job Result

Poll `/v1/requests/{request_id}` for the result:

<ResponseField name="result.output" type="string | object">
  Extracted data or task result. Structured JSON if you passed `output_schema`.
</ResponseField>

<ResponseField name="result.steps" type="array">
  List of steps taken: `[{ number, goal, url }]`
</ResponseField>

<ResponseField name="result.cost" type="number">
  Actual cost incurred
</ResponseField>

<ResponseField name="result.output_files" type="string[]">
  URLs of any files downloaded or screenshots captured
</ResponseField>

<RequestExample>
  ```bash cURL (Get Quote) theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/browser \
    -H "Content-Type: application/json" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -d '{
      "task": "Go to producthunt.com, find the top 5 AI products launched today, and extract their names, descriptions, and upvote counts",
      "output_schema": {
        "products": [{
          "name": "string",
          "description": "string",
          "upvotes": "number"
        }]
      }
    }'
  ```

  ```typescript SDK theme={null}
  import { OneShot } from "@oneshot-agent/sdk";

  const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

  const result = await agent.browser({
    task: "Go to producthunt.com, find the top 5 AI products launched today, and extract their names, descriptions, and upvote counts",
    output_schema: {
      products: [{
        name: "string",
        description: "string",
        upvotes: "number"
      }]
    }
  });

  console.log("Products:", result.output.products);
  console.log("Steps taken:", result.steps.length);
  ```

  ```typescript SDK (with profile + secrets) theme={null}
  import { OneShot } from "@oneshot-agent/sdk";

  const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

  // Create a persistent profile
  const profile = await agent.createBrowserProfile("my-github-bot");

  // Use the profile with credentials
  const result = await agent.browser({
    task: "Go to github.com/notifications and list my unread notifications",
    profile_id: profile.id,
    secrets: { "github.com": "myuser:ghp_xxxxxxxxxxxx" },
    allowed_domains: ["github.com"],
  });
  ```

  ```python Python SDK theme={null}
  from oneshot import OneShotClient

  client = OneShotClient(private_key="0x...")

  # Create a persistent profile
  profile = client.create_browser_profile("my-github-bot")

  # Use the profile with credentials
  result = client.browser(
      task="Go to github.com/notifications and list my unread notifications",
      profile_id=profile["id"],
      secrets={"github.com": "myuser:ghp_xxxxxxxxxxxx"},
      allowed_domains=["github.com"],
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Quote Response (402) theme={null}
  {
    "error": "payment_required",
    "message": "Payment required for browser automation.",
    "payment_request": {
      "chain_id": 8453,
      "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "0.150000",
      "recipient": "0x..."
    },
    "context": {
      "tool": "browser",
      "quote_id": "quote_abc123",
      "task_summary": "Navigate to ProductHunt, find top AI products, extract structured data",
      "estimated_steps": 8,
      "max_steps": 25,
      "estimated_cost": "0.150000",
      "complexity_score": 0.6,
      "expires_at": "2026-01-15T12:30:00Z"
    }
  }
  ```

  ```json Execution Response (202) theme={null}
  {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "tool": "browser",
    "message": "Browser task initiated. Results available at /v1/requests/{id}.",
    "browser": {
      "estimated_steps": 8,
      "max_steps": 25,
      "estimated_cost": "0.150000"
    }
  }
  ```

  ```json Completed Result theme={null}
  {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "result": {
      "output": {
        "products": [
          { "name": "AgentKit", "description": "Build autonomous AI agents in minutes", "upvotes": 342 },
          { "name": "VoiceFlow", "description": "AI voice agents for customer support", "upvotes": 289 }
        ]
      },
      "steps": [
        { "number": 1, "goal": "Navigate to producthunt.com", "url": "https://www.producthunt.com" },
        { "number": 2, "goal": "Find AI products section", "url": "https://www.producthunt.com/topics/artificial-intelligence" }
      ],
      "cost": 0.12
    }
  }
  ```
</ResponseExample>

<Info>Charged per step with a base initialization fee and margin. See [Pricing](/pricing) for details.</Info>

<Tip>Pass `output_schema` to get structured JSON back instead of raw text.</Tip>

<Tip>`allowed_domains` keeps the browser on-target and cuts both cost and runtime.</Tip>