Agent Endpoints

Choose the right TinyFish Agent endpoint based on sync, async, or streaming needs

TinyFish Web Agent offers three ways to run automations. Each endpoint serves a different need. Pick the one that matches how you want to handle the request and response.

The Three Endpoints

Endpoint	Pattern	Best For
/run	Synchronous	Quick tasks, simple integrations
/run-async	Start then check	Long tasks, batch processing
/run-sse	Live updates	Real-time progress, user-facing apps

---

Synchronous: /run

Pattern: Send request → Wait → Get result

The simplest approach. You call the API, it blocks until the automation completes, then returns the result.

import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();

const run = await client.agent.run({
  url: "https://example.com",
  goal: "Extract the page title",
});

console.log(run.result); // Your data

Runs created via /run cannot be cancelled. The request blocks until the automation completes, so there is no window to issue a cancellation. If you need the ability to cancel runs, use /run-async or /run-sse instead.

When to use

• Tasks that complete in under 30 seconds
• Simple scripts and one-off automations
• When you don’t need progress updates

When to avoid

• Long-running tasks (risk of timeout)
• User-facing apps (no progress feedback)
• Batch processing (blocks other requests)
• When you need the ability to cancel a run

---

Asynchronous: /run-async

Pattern: Send request → Get run ID → Poll for result

The request returns immediately with a run_id. You then poll a separate endpoint to check status and get the result when ready.

1. Start the automation

import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();

const queued = await client.agent.queue({
  url: "https://example.com",
  goal: "Extract all product data",
});

if (queued.error) {
  throw new Error(`Failed to queue run: ${queued.error.message}`);
}

const runId = queued.run_id;

2. Poll for the result

const run = await client.runs.get(runId);
// run.status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
// run.result: Your data (when COMPLETED)

3. Cancel a run (optional)

If you need to stop a run before it completes, send a POST to the cancel endpoint:

await fetch(`https://agent.tinyfish.ai/v1/runs/${runId}/cancel`, {
  method: "POST",
  headers: { "X-API-Key": process.env.TINYFISH_API_KEY },
});

Learn more about run statuses and lifecycle in Runs.

When to use

• Long-running automations (30+ seconds)
• Batch processing multiple URLs
• Fire-and-forget workflows
• When you need to track runs separately

When to avoid

• When you need real-time progress updates
• Simple, quick extractions (adds complexity)

---

Streaming: /run-sse

Pattern: Send request → Receive event stream → Process events as they arrive

Uses Server-Sent Events (SSE) to push updates to you in real-time. You’ll receive events for each action the browser takes, plus a streaming URL you can embed in an iframe to watch the automation live.

1. Start the automation and read events

import { TinyFish, EventType } from "@tiny-fish/sdk";

const client = new TinyFish();

const stream = await client.agent.stream({
  url: "https://example.com",
  goal: "Extract all product data",
});

for await (const event of stream) {
  console.log(event.type, event);
}

Event Types

Event	Description
STARTED	Automation has begun, includes run_id
STREAMING_URL	URL to watch the browser live (valid 24hrs)
PROGRESS	Browser action taken (click, type, scroll, etc.)
HEARTBEAT	Connection keep-alive (no action needed)
COMPLETE	Automation finished, includes status and result

Cancelling an SSE Run

You can cancel a streaming run using the run_id from the STARTED event. The onStarted callback fires while you consume the stream, so capture run_id there and trigger the cancel from a separate context (here, a deadline timer):

let runId: string | undefined;

const stream = await client.agent.stream(
  { url: "https://example.com", goal: "Extract all product data" },
  { onStarted: (e) => { runId = e.run_id; } },
);

// Cancel from another context while the stream is being consumed.
const deadline = setTimeout(() => {
  if (runId) {
    fetch(`https://agent.tinyfish.ai/v1/runs/${runId}/cancel`, {
      method: "POST",
      headers: { "X-API-Key": process.env.TINYFISH_API_KEY },
    });
  }
}, 30000);

for await (const event of stream) {
  console.log(event);
}
clearTimeout(deadline);

Handling Events

Use this pattern to process each event type as the automation progresses.

import { TinyFish, EventType, RunStatus } from "@tiny-fish/sdk";

const client = new TinyFish();

const stream = await client.agent.stream(
  { url: "https://example.com", goal: "Extract all product data" },
  {
    onStarted: (e) => console.log(`Run started: ${e.run_id}`),
    onStreamingUrl: (e) => console.log(`Watch live: ${e.streaming_url}`),
    onProgress: (e) => console.log(`Action: ${e.purpose}`),
    onComplete: (e) => {
      if (e.status === RunStatus.COMPLETED) {
        console.log("Result:", e.result);
      } else {
        console.error(e.error?.message || "Automation failed");
      }
    },
  },
);

for await (const event of stream) {
  // Callbacks fire automatically during iteration
}

When to use

• User-facing apps (show progress)
• When you want to watch the browser live
• Debugging and development
• Long tasks where you want visibility

When to avoid

• Batch processing (complexity overhead)
• Backend jobs that don’t need progress

---

Common Request Options

All three endpoints accept the same request body. Beyond the required url and goal, these optional fields apply across /run, /run-async, and /run-sse:

Field	Type	Description
agent_config.max_steps	number	Maximum tool-call steps before the agent stops (in beta — join the beta to use it). 1–500, defaults to 150. See Runs.
agent_config.max_duration_seconds	number	Maximum wall-clock seconds before the agent stops. Defaults to no limit.
agent_config.mode	string	Agent behavior mode. strict (in beta — join the beta to use it) enables fail-fast for test automation. See Runs.
capture_config	object	Toggle which data to capture during the run (screenshots, html, recording, etc.). html: true is required for per-step HTML snapshots.
webhook_url	string	HTTPS URL to receive run lifecycle notifications. Must use HTTPS.

{
  "url": "https://example.com",
  "goal": "Extract all product data",
  "agent_config": {
    "max_steps": 50,
    "max_duration_seconds": 300
  },
  "capture_config": { "html": true },
  "webhook_url": "https://your-app.example.com/webhooks/tinyfish"
}

For authenticated runs and runtime browser modes, see Browser Profiles and the Browser Context Profiles API.

---

Quick Decision Guide

1. Need real-time progress updates?

   Yes → Use /run-sse

2. Task takes longer than 30 seconds?

   Yes → Use /run-async + polling

3. Submitting multiple tasks at once?

   Yes → Use /run-async (parallel submission)

4. Simple, quick task?

   Use /run (synchronous)

---

Comparison Table

Feature	/run	/run-async	/run-sse
Response type	Final result	Run ID	Event stream
Progress updates	No	No (poll status)	Yes
Streaming URL	In response	Poll to get	In events
Cancellable	No	Yes	Yes
Best for	Quick tasks	Batch/long tasks	Real-time UI
Complexity	Low	Medium	Medium

---

Related

Runs

Understand the automation lifecycle

API Reference

Full endpoint specifications