Agent API

Execute autonomous browser tasks with AI. Submit a natural-language instruction and the agent creates a session, plans actions, and executes them automatically. Poll for status or cancel at any time.

Workflow

Submit — POST an instruction to /api/agent/execute. Returns a taskId immediately.
Poll — GET /api/agent/:taskId/status until the status is terminal (completed, failed, or timeout).
Cancel (optional) — POST /api/agent/:taskId/cancel to abort a running task.

Endpoints

POST/api/agent/execute

Start an autonomous agent task. The agent creates a browser session, plans actions based on your instruction, and executes them automatically.

Body Parameters

instructionstringrequiredNatural-language instruction for the agent (max 10,000 chars)

backendstringAI backend: "gemini" (default) or "claude"

timeoutMsnumberExecution timeout in ms (30000–600000, default 300000)

Response

{
  "success": true,
  "data": {
    "taskId": "a1b2c3d4-...",
    "sessionId": "e5f6g7h8-...",
    "status": "starting",
    "backend": "gemini"
  },
  "message": "Agent execution delegated to browser machine. Poll /api/agent/:taskId/status for progress."
}

GET/api/agent/:taskId/status

Poll the status of an agent task. Returns current progress, output, and final result when complete.

Query Parameters

sessionIdstringSession ID hint for cross-machine polling (optional)

Response

{
  "success": true,
  "data": {
    "taskId": "a1b2c3d4-...",
    "status": "completed",
    "output": "Successfully navigated to example.com and extracted the page title.",
    "startedAt": "2026-02-09T12:00:00Z",
    "completedAt": "2026-02-09T12:00:15Z"
  }
}

POST/api/agent/:taskId/cancel

Cancel a running agent task. The task must be owned by the authenticated user.

Response

{
  "success": true,
  "message": "Agent task cancelled"
}

Task Statuses

Status	Terminal	Description
starting	No	Session is being provisioned
pending	No	Waiting for machine to be ready
running	No	Agent is executing browser actions
completed	Yes	Task finished successfully
failed	Yes	Task encountered an error
timeout	Yes	Task exceeded the timeout limit
cancelled	Yes	Task was cancelled by the user

MCP Page Cache Tools

Three stateless MCP tools — no sessionId required. Install: npx @thinkrun/mcp. Cloud mode consumes credits; local is free.

Tool	REST endpoint	Credits (cloud)	Description
page_cache_html	POST /api/cache/html	1	Fetch rendered HTML. Returns `{ html, metadata }`
page_cache_text	POST /api/cache/text	1	Extract plain text. Returns `{ text, metadata }`
page_cache_screenshot	POST /api/cache/screenshot	3	Capture PNG. Returns `{ artifactUrl, metadata }`

All three tools accept url (required) and options (optional). Key options: provider (cloud|local), sensitive, waitFor, timeout, fullPage, maxDimension. Set options.sensitive: true to prevent the URL from being sent to third-party scrapers.