Agent run

Give a start URL and a goal in plain language. A TinyFish web agent operates a real browser (navigating, clicking, filling forms) and returns a structured JSON result.

POST/api/v1/agent/run50000 base units · 0.05 USDT

Body

Field	Type
`url`	string	Required. Start URL.
`goal`	string	Required. What to do and what to return.
`output_schema`	JSON Schema	Optional. Shapes `result` predictably.
`browser_profile`	`lite` \| `stealth`	`stealth` uses an anti-detection browser.
`agent_config.mode`	`default` \| `strict`	`strict` fails fast.
`agent_config.max_steps`	integer	1–500.
`agent_config.max_duration_seconds`	integer	Capped at 280 seconds so the run fits inside one request. Use `strict` mode or fewer steps for long tasks.
`proxy_config`	`{ enabled, country_code? }`	Route the run through a country.

Vault credentials, browser profiles and webhooks are scoped to the operator's account, so they are not exposed. Unknown fields are dropped.

Example

const res = await paidFetch("https://your-domain.com/api/v1/agent/run", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://news.ycombinator.com",
    goal: "Return the top 3 stories with title, url and points.",
    output_schema: {
      type: "object",
      properties: {
        stories: {
          type: "array",
          items: {
            type: "object",
            properties: { title: { type: "string" }, url: { type: "string" }, points: { type: "integer" } },
            required: ["title", "url"],
          },
        },
      },
      required: ["stories"],
    },
  }),
});

Response

json

{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "started_at": "2026-11-06T10:00:00Z",
  "finished_at": "2026-11-06T10:00:31Z",
  "num_of_steps": 5,
  "result": { "stories": [{ "title": "…", "url": "https://…", "points": 412 }] },
  "error": null
}

A run with status: "FAILED" is returned as 502 with its error (code, message, category) and is not charged.

Want live progress? Use Agent run (SSE).