--- title: TinyFish API Integration on Truto slug: tinyfish category: Application Development canonical: "https://truto.one/integrations/detail/tinyfish/" --- # TinyFish API Integration on Truto **Category:** Application Development **Status:** Generally available ## MCP-ready AI tools Truto exposes 43 tools for TinyFish that AI agents can call directly. - **delete_a_tiny_fish_browser_context_profile_domain_by_id** — Remove one saved domain (its cookies and storage) from a Browser Context Profile. Required: id, profile_id. - **create_a_tiny_fish_browser_context_profile_setup_session** — Start a temporary setup browser for a Browser Context Profile. Returns session_id and cdp_url: connect a CDP client (Playwright, Puppeteer) to cdp_url, log in, then save with browser_context_profile_setup_sessions.complete before expires_at. Required: profile_id. - **tiny_fish_browser_context_profile_setup_sessions_cancel** — Cancel a running profile setup session and discard its unsaved state. Required: profile_id, session_id. - **tiny_fish_browser_context_profile_setup_sessions_complete** — Save a running setup session into its Browser Context Profile: captures cookies, local storage and session storage per domain. Saving again returns the first save's result. Required: profile_id, session_id. - **create_a_tiny_fish_browser_context_profile_state** — Upload browser state into a Browser Context Profile: cookies, plus optional localStorage and sessionStorage per origin. Required: profile_id, cookies. - **list_all_tiny_fish_browser_context_profiles** — List Browser Context Profiles: saved logged-in browser state (cookies, local and session storage per domain) that runs reuse via profile_id. - **create_a_tiny_fish_browser_context_profile** — Create an empty Browser Context Profile. Fill it by logging in through browser_context_profile_setup_sessions.create or by uploading cookies with browser_context_profile_states.create. Required: name. - **get_single_tiny_fish_browser_context_profile_by_id** — Get a Browser Context Profile and its saved domains. Required: id. - **update_a_tiny_fish_browser_context_profile_by_id** — Rename a Browser Context Profile, make it the default, or change its proxy country. Required: id. - **delete_a_tiny_fish_browser_context_profile_by_id** — Delete a Browser Context Profile and its saved state. Required: id. - **list_all_tiny_fish_browser_session_usage_records** — List remote browser session usage: duration, data transfer, mode and status per session. - **create_a_tiny_fish_browser_session** — Create a remote browser session. Returns session_id and cdp_url: drive the browser over CDP (Playwright, Puppeteer). Spends wallet credit while it runs; end it with browser_sessions.delete. - **delete_a_tiny_fish_browser_session_by_id** — Terminate a remote browser session at once. Idempotent: an ended session also returns success. Required: id. - **list_all_tiny_fish_fetch_usage_records** — List Fetch API usage records: URL, format, status and metadata per fetch. - **create_a_tiny_fish_fetch** — Fetch up to 10 URLs and get clean extracted content (markdown, html or json), rendering JavaScript pages when needed. Per-URL failures are listed in errors without failing the request. Free within a daily allowance. Required: urls. - **create_a_tiny_fish_monitor_run** — Run a Monitor now, outside its schedule. Returns the new run. Required: monitor_id. - **create_a_tiny_fish_monitor** — Create a Monitor that runs on a cron schedule: type fetch watches a page (config url), type search watches a topic (config query). Captures a baseline run at once and can post each run's results to webhook_url. Required: schedule_cron, type, config. - **list_all_tiny_fish_monitors** — List Monitors (scheduled page or topic watches) with their schedule, status and latest run. - **get_single_tiny_fish_monitor_by_id** — Get a Monitor with its schedule, status and runs. Required: id. - **update_a_tiny_fish_monitor_by_id** — Pause or resume a Monitor (send status alone), or edit it (schedule_cron, with optional name, webhook_url and purpose). Required: id. - **delete_a_tiny_fish_monitor_by_id** — Delete a Monitor and its schedule. Required: id. - **create_a_tiny_fish_research_run** — Start a research run: TinyFish searches the web, evaluates sources and writes a cited report for query. Returns research_run_id at once; poll research_runs.get (usually several minutes). 2 free completed runs a day, then billed; up to 5 at once. Required: query. - **list_all_tiny_fish_research_runs** — List saved research runs, newest first, filterable by status, query text and created date range. - **get_single_tiny_fish_research_run_by_id** — Get a research run: status, query, quick and deep results (the cited report), plan, evidence and per-iteration state. Poll this after research_runs.create. Required: id. - **tiny_fish_research_runs_cancel** — Cancel a running research run. Idempotent: a finished run returns cancelled false and its current status. Required: research_run_id. - **list_all_tiny_fish_run_step_html_snapshots** — Get the full-page HTML captured at one step of a run (raw text/html). Only for runs started with capture_config html set to true; the final "Task completed" step has none (404). Required: run_id, step_id. - **list_all_tiny_fish_run_step_screenshots** — Download the JPEG screenshot captured at one step of a run (binary image/jpeg). Step IDs are in the steps of runs.get; the final "Task completed" step has no screenshot (404). Required: run_id, step_id. - **tiny_fish_runs_execute** — Run a web automation and wait for it: TinyFish opens url in a real browser, follows the goal and returns the finished run (COMPLETED or FAILED, result JSON). For short tasks only; use runs.create for long ones. Spends wallet credit. Required: url, goal. - **create_a_tiny_fish_run** — Start a web automation asynchronously and get its run_id at once. TinyFish opens url in a real browser and works through the natural-language goal. Poll runs.get until status is COMPLETED, FAILED or CANCELLED (or set webhook_url); stop it with runs.cancel. Spends wallet credit. Required: url, goal. - **tiny_fish_runs_bulk_create** — Start up to 100 web automations in one request, each with its own url and goal. Returns their run_ids in order; poll them with runs.bulk_get. Spends wallet credit per run. Required: runs. - **list_all_tiny_fish_runs** — List automation runs, newest first, filterable by status, goal text and created date range. Each run has run_id, status, goal, result and timing. - **tiny_fish_runs_bulk_get** — Get up to 100 runs by ID in one request. Found runs are in data; unknown or not-owned IDs are listed in not_found. Runs here omit steps and video_url; use runs.get for those. Required: run_ids. - **tiny_fish_runs_bulk_cancel** — Cancel up to 100 runs by ID. Returns a result per run (cancelled, or already finished) and the IDs not found. Idempotent. Required: run_ids. - **get_single_tiny_fish_run_by_id** — Get one automation run: status (PENDING, RUNNING, COMPLETED, FAILED, CANCELLED), goal, result JSON, error, steps, timing and the live streaming_url. Poll this after runs.create. Required: id. - **tiny_fish_runs_cancel** — Cancel a pending or running automation started with runs.create. Runs from runs.execute can't be cancelled. Required: run_id. - **list_all_tiny_fish_search_results** — Search the web and get ranked results (title, snippet, url) for query, with optional location, language, domain filters, date ranges and news or research-paper modes. Free within a daily allowance. Required: query. - **list_all_tiny_fish_search_usage_records** — List Search API usage records: query details, status and result counts. - **create_a_tiny_fish_vault_connection** — Connect a password manager (1Password service-account token, or Bitwarden client ID, secret and master password) so runs can log in to websites with its credentials. Syncs display-safe item metadata at once. Required: provider. - **list_all_tiny_fish_vault_connections** — List the password managers (vault providers) connected to TinyFish. - **delete_a_tiny_fish_vault_connection_by_id** — Disconnect a vault provider and remove its stored enabled items. Required: id. - **create_a_tiny_fish_vault_item_sync** — Re-sync items from the connected vault providers. Returns the merged items and sync counters. - **list_all_tiny_fish_vault_items** — List the credential items available from connected vaults (display-safe metadata, no secrets). Pass their IDs as credential_item_ids when starting a run with use_vault. - **list_all_tiny_fish_wallets** — Get the wallet: available balance, currency, auto-reload settings, per-product rates and any pending top-up. Accounts on legacy credit plans get 404 FEATURE_NOT_AVAILABLE. ## How it works 1. **Link your customer's TinyFish account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach TinyFish.** The Proxy API is a 1-to-1 mapping of the TinyFish API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed autonomous web execution in AI copilots** — AI agent platforms can give their users a reliable 'take action on the web' primitive by routing goals through TinyFish runs via Truto. Instead of maintaining headless browser infrastructure, you deliver natural-language web automation as a native feature. - **Offer authenticated data pulls from portals without APIs** — Marketing, procurement, and finance SaaS products can let users pull data from vendor portals, ad networks, and legacy systems that lack public APIs. Truto brokers the TinyFish vault connection and run execution so your users keep credentials in their own password manager. - **Ship competitive and brand monitoring as a native feature** — PR, pricing, and competitive intelligence platforms can programmatically create TinyFish monitors on behalf of their users and receive webhook alerts when pages or search topics change. Truto handles the connection lifecycle so you can focus on surfacing insights. - **Power deep research workflows inside your product** — Analytics, consulting, and market intelligence SaaS can expose a 'Research' button that triggers TinyFish research_runs and returns a cited report. Truto standardizes auth and polling so you can embed this without building a research engine. - **Bulk enrich records with live web data** — CRMs and sales platforms can trigger bulk TinyFish runs against lists of domains to extract hiring signals, pricing, or company data on a schedule. Truto lets you offer this to every customer under their own TinyFish account. ## What you can build - **Natural-language web task runner** — Let users describe a web task in plain English and execute it via TinyFish runs, surfacing step-by-step screenshots and HTML snapshots as an audit trail. - **User-owned vault-backed automation** — Allow end users to connect their password manager through TinyFish vault_connections so your product can run authenticated workflows without ever touching their credentials. - **Scheduled page and topic monitors** — Programmatically create and manage TinyFish monitors from your UI so users can track competitor pages, pricing changes, or brand mentions with webhook-driven alerts. - **One-click deep research reports** — Expose TinyFish research_runs as a feature that produces fully cited reports from a single query, with cancel and status controls built in. - **Bulk web extraction pipelines** — Use bulk run creation to process thousands of URLs in parallel for lead enrichment, catalog scraping, or market data collection, with per-run status tracking. - **Reusable browser context profiles** — Let users complete a one-time 2FA or captcha via a TinyFish setup session, then reuse that browser context profile for all subsequent background automations. ## FAQs ### How do end users authenticate their TinyFish account? Through Truto's connection flow, your users provide their TinyFish API credentials once. Truto securely stores and injects them for every API call, so you never handle keys directly. ### Can users connect their own password manager for authenticated runs? Yes. TinyFish supports vault connections (e.g., 1Password, Bitwarden) via create_a_tiny_fish_vault_connection, and Truto exposes the full lifecycle including listing vault items and syncing them into runs. ### How do we handle long-running automations like runs and research_runs? TinyFish operations are asynchronous. You create a run or research_run, then poll the get-by-id endpoint or listen for completion. Truto normalizes the request/response shape so you can wire up webhooks or polling in your product. ### Can we execute runs in bulk? Yes. Truto exposes tiny_fish_runs_bulk_create, tiny_fish_runs_bulk_get, and tiny_fish_runs_bulk_cancel so you can fan out hundreds or thousands of URL+goal pairs and manage them as a batch. ### How do we handle 2FA or captchas on target sites? Use browser context profiles. Create a setup session via create_a_tiny_fish_browser_context_profile_setup_session, let the user solve the challenge once in the CDP URL, complete the session, and reuse the saved profile for future runs. ### Can we audit what happened during an automated run? Yes. Truto surfaces list_all_tiny_fish_run_step_screenshots and list_all_tiny_fish_run_step_html_snapshots so you can show users (or your compliance team) exactly what the agent saw and did at each step. ### Is this integration available today? TinyFish is available on Truto as a native integration covering runs, research_runs, monitors, fetch, browser_sessions, browser_context_profiles, and vault_connections. If you need additional endpoints or a unified abstraction across similar providers, Truto can build it on request.