TinyFish

Run a TinyFish web agent on a real website and wait for it to finish: give a starting URL and a plain-language goal; the answer is the run with its structured result (status COMPLETED or FAILED, with the reason). Waits as long as the run takes and cannot be cancelled — bound it with agent_config.max_duration_seconds, or use start_automation + get_run for long goals. Spends your TinyFish wallet per step.

Start a TinyFish web agent run and return its run_id at once; poll get_run (or get_runs) for the result, cancel_run to stop it. Same inputs as run_automation. Spends your TinyFish wallet per step.

Start 1–100 web agent runs in one request and return their run_ids. All-or-nothing; not idempotent — a retry after an unclear failure can start duplicates, so check list_runs first. profile_id and output_schema apply to every run.

List your web agent runs, newest first: filter by status, goal text and creation window; page with cursor.

Get one web agent run: status, goal, result, error (with its category and retry hint), steps and timing. screenshots: none omits them, base64 inlines every step's JPEG (large), url returns links that need a TinyFish session — to look at one step, use get_run_step_screenshot.

Get up to 100 web agent runs by id in one request; ids not found (or not yours) come back in not_found.

Cancel a running or pending web agent run (started with start_automation or start_automations). Idempotent: a finished run is left as it is. A run_automation run cannot be cancelled.

Cancel up to 100 web agent runs by id; the answer says which were cancelled, already finished, or not found. Idempotent.

Start a TinyFish research run: it searches, weighs sources and writes a cited report for a natural-language question. Returns research_run_id at once; poll get_research_run for the report. Spends your TinyFish wallet.

List your research runs: filter by status, query text and creation window; page with cursor (valid only with the same sort_direction).

Get one research run: its status, plan, evidence and, once COMPLETED, the cited report.

Cancel a running research run. Idempotent: a finished run answers cancelled: false with its status.

Search the web with TinyFish (free): ranked results with titles, snippets and URLs. domain_type picks web, news or research papers; location / language default to US / en, each resolving the other when only one is set.

List your past TinyFish searches: query, status and result count.

Fetch 1–10 pages with TinyFish (free), rendering JavaScript when needed, and return clean content (markdown by default, html or json). One URL failing does not fail the others: its error is in errors[]. Long pages are trimmed to fit; narrow with include_selectors.

List your past TinyFish fetches: URL, format and status.

Start a remote Chrome session and return its CDP WebSocket URL (cdp_url) for Playwright, Puppeteer or any CDP client. Egresses through TinyFish's US residential proxy by default. Bills per browser-minute until it times out or terminate_browser_session closes it.

List your remote browser sessions with duration, data transfer and status (running or ended).

Close a remote browser session now. Idempotent: an ended session answers the same.

List your Browser Context Profiles — saved cookies and storage that let web agent runs start signed in.

Create a Browser Context Profile; sign it in with start_profile_setup_session or upload_profile_state.

Get one Browser Context Profile and the sites it holds a session for.

Rename a Browser Context Profile, make it the default, or change its proxy country.

Delete a Browser Context Profile and its saved sessions. The only remaining profile cannot be deleted.

Open a temporary setup browser for a profile and return its cdp_url: connect a CDP client (Playwright, Puppeteer), sign in to the sites the runs need, then save_profile_setup_session. Unsaved state is discarded on cancel or timeout.

Cancel a profile setup session and discard what it had not saved.

Save a running setup session's cookies, local storage and session storage into its profile.

Write cookies (and optionally localStorage / sessionStorage entries) into a profile directly, e.g. exported from a signed-in browser.

Forget one site's saved session in a profile.

List the password managers connected to TinyFish (connect one in TinyFish's dashboard).

List the credential items your connected password managers expose to runs — display-safe metadata only, never secrets. Pass their ids as credential_item_ids with use_vault.

Re-sync credential items from your connected password managers and return the merged list.

Disconnect a password manager from TinyFish and remove its enabled items.

Watch a page (page) or a search topic (topic) on a cron schedule; TinyFish compares each run to the last and judges changes against purpose. Answers the monitor and its baseline run. Scheduled results go to webhook_url; email is set up in TinyFish's dashboard.

List your page and topic monitors.

Get one monitor: its target, schedule, status and last error. Run history lives in TinyFish's dashboard.

Change a monitor's schedule, name, purpose or webhook (null clears the last three). schedule_cron is required on every edit — read the current one with get_monitor. The page or topic itself cannot change; pause with set_monitor_status.

Pause a monitor's schedule (paused) or resume it (active); history is kept.

Run a monitor now and return the result (no webhook or email is sent for it).

Delete a monitor, its schedule and its run history.

Read your TinyFish wallet: balance, auto-reload settings, per-product rates and any top-up in flight. Accounts not on wallet billing answer FEATURE_NOT_AVAILABLE.

Look at one web agent run step: the JPEG screenshot TinyFish captured at it, as an image. Step ids come from get_run.

Read the full-page HTML TinyFish saved at one web agent run step — only for runs started with capture_config.html: true. Long pages are trimmed to fit.