How to connect TinyFish with Python

Runs a browser automation task and streams its Server-Sent Events to completion synchronously, blocking until a terminal `COMPLETE` event arrives, then returns the run ID, final status, result payload, streaming URL (if the upstream sent one), accumulated progress messages, and completion timestamp. `webhook_url` must be HTTPS, `credential_item_ids` requires `use_vault: true`, `output_schema` is validated before the run is accepted, and `use_profile` returns a 400 if enabled but no default Browser Context Profile is set.

Creates and enqueues a browser automation run, returning its `run_id` immediately without waiting for the run to finish. Poll a separate status tool with the `run_id`, or supply an HTTPS `webhook_url` for push notifications instead; `credential_item_ids` requires `use_vault: true`, `output_schema` is validated before the run is accepted, and `use_profile` returns a 400 if enabled but no default Browser Context Profile is set.

Executes a browser automation task synchronously, blocking until it finishes, and returns the final status, result, and error in one response. Runs created this way cannot be cancelled — use `start_automation_async` or `run_browser_automation_sse` instead if you need cancellation support.

Lists automation runs with optional filtering by status, goal text, and creation date range. Returns paginated run summaries plus a total count, sorted newest-first by default; pass the `cursor` from a previous response's `pagination.next_cursor` to page through further results.

Retrieves full details for a single automation run by ID, including its status, goal, extracted result, step-by-step trace, and any error information. Use `screenshots` and `html` to control whether screenshot and HTML snapshot URLs are included in the response.

Cancels an in-progress automation run by ID. Only runs started via the async or SSE automation endpoints can be cancelled — a run started via the synchronous automation endpoint cannot be. This call is idempotent: calling it again on a run that is already cancelled or already finished still returns 200, with the run's actual current status and an explanatory `message` instead of an error.

Retrieves multiple automation runs by ID in a single request, returning each found run's status, goal, result, and error alongside a list of any IDs that were not found or not owned by the caller. Accepts 1-100 IDs per call.

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Cancels multiple in-progress automation runs by ID in a single bulk call (1-100 IDs). Only runs started via the async or SSE automation endpoints can be cancelled this way. This is idempotent per run — a run already in a terminal state (e.g. `COMPLETED`) is reported with its actual current status and an explanatory message rather than an error — but a per-run before-state is not returned and cannot be recovered from this call. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user exactly which runs will be cancelled, and wait for their explicit written confirmation before proceeding.

Retrieves the JPEG screenshot captured at a specific automation run step, authenticated with the API key. Returns the image as base64-encoded bytes with its content type.

Retrieves the full-page HTML snapshot captured at a specific automation run step, authenticated with the API key. Only available when the run was started with `capture_config.html: true`.

Searches the web and returns ranked results with titles, snippets, and URLs, plus the total result count and current page. Location and language each auto-resolve from the other when only one is set (defaulting to US/en if neither is set); `page` is capped at 10; and `pub_year_min`/`pub_year_max` only apply when `domain_type` is `research_paper`.

Lists search usage records for the authenticated user, returning paginated query details, status codes, and result counts. `limit` defaults to 100 and is capped at 1000; `page` defaults to 1; filter by `status` of `completed` or `failed`.

Fetches 1-10 URLs in parallel (rendering JavaScript-heavy pages when needed) and returns clean extracted content as markdown (default), HTML, or a structured JSON document tree. Each URL is processed independently — a per-URL failure is reported in `errors` without failing the rest of the batch.

Lists fetch usage records for the authenticated user — URL, format, status, and metadata for each past fetch operation — with page-based pagination (`page`/`limit`, `total_pages`, `has_more`) and optional filtering by `status` (`completed` or `failed`) and time range.

Retrieves the caller's wallet: current balance, auto-reload configuration, per-product contract rates, and any in-flight top-up. `auto_reload: null` means the auto-reload contract read failed (not that auto-reload is unconfigured — that state lives inside the object itself); `pending_top_up: null` and `rates: null` are each ambiguous between a normal empty state and a backend read failure. `agent_top_up_url` is present only when the agent can add funds itself, by posting there to pay the 402 MPP challenge.

Starts a wallet top-up for a USD `amount` and returns a payment challenge — this call alone never moves money, and is as safe as a read despite its CREATE tier. Hand the challenge to the caller's own external MPP-speaking wallet (e.g. Stripe's Link agent wallet) to obtain a `Payment-Authorization` credential — this tool cannot produce one itself — then call `confirm_wallet_topup` with the same amount and that credential to actually settle the charge. The challenge expires 30 minutes after this call.

Settles a wallet top-up previously started with `request_wallet_topup`, using a `payment_authorization` credential obtained from the caller's own external MPP-speaking wallet for that specific challenge. Requires calling `request_wallet_topup` first — this tool cannot be used cold and cannot generate a credential on its own. A `402` response here (without a fresh challenge) means the payment was sent but not accepted — never retry this call on your own in that case; a replayed credential is never charged twice, but stop and check the wallet balance before starting a new top-up.

Creates a new Browser Context Profile — a reusable, isolated browser identity (cookies, local storage, fingerprint) that automation runs can attach to. Returns the created profile's ID and metadata.

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Permanently deletes the Browser Context Profile identified by `profileId`, including all its saved cookies, local storage, and session storage for every domain. This action is irreversible — the saved browser state cannot be recovered. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user exactly what will be deleted and that it is permanent, and wait for their explicit written confirmation before proceeding.

Updates a Browser Context Profile's name, default status, or proxy country, returning the full updated profile. Only the fields you provide are changed — others keep their current value. A 'before' snapshot isn't available: this bundle has no confirmed endpoint yet for fetching a single profile ahead of the update.

Starts a temporary setup browser for a Browser Context Profile, returning a `cdp_url` to drive it with Playwright, Puppeteer, or any CDP client. Log in during the session, then call `save_profile_setup_session` with the returned `session_id` to persist it — unsaved state is discarded if the session is cancelled or expires.

Cancels a running Browser Context Profile setup session and discards any unsaved setup state. Requires the `session_id` returned by `create_profile_setup_session`.

Captures cookies, local storage, and session storage from a running setup session into the Browser Context Profile. Requires the `session_id` returned by `create_profile_setup_session`; writes/merges domain state into the existing profile rather than creating a new one.

Uploads cookies, local storage, and session storage directly into a Browser Context Profile, without running a live setup browser session. Writes/merges the given domain state into the existing profile.

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Permanently removes one domain's saved state (e.g. cookies for that site) from a Browser Context Profile, leaving the rest of the profile untouched. This action is irreversible — the saved state for that domain cannot be recovered. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user exactly which domain will be removed from which profile and that it is permanent, and wait for their explicit written confirmation before proceeding.

Connects a supported password manager (1Password or Bitwarden) and immediately syncs its display-safe credential metadata. Returned items carry only metadata (labels, domains, field types) — actual secret values are never included.

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Permanently disconnects the vault provider connection identified by `connectionId` and removes all of its stored enabled items. This action is irreversible — the connection and its synced item metadata cannot be recovered; reconnecting requires the provider's credentials again. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user exactly what will be disconnected and that it is permanent, and wait for their explicit written confirmation before proceeding.

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Re-syncs items across every connected vault provider in one bulk call, returning the full merged item list plus added/updated/removed counts. This overwrites the current item state for every connected provider — the original per-item values before this sync are not returned and cannot be recovered from this call. There is no way to target a single provider or item. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user that this will re-sync all connected vault providers, and wait for their explicit written confirmation before proceeding.

Runs a research task — searching, evaluating sources, and synthesizing a cited report — and streams its progress to completion synchronously, blocking until the terminal `done` event. Returns the research run ID, the synthesized report, its citations, and the plan iterations seen along the way. Always streams, even when `stream` is false; `prior_run_id` and `session_id` are mutually exclusive.

Enqueues a research task and returns its `research_run_id` immediately after durable dispatch, without waiting for completion. Poll `get_research_run` or attach with `attach_research_progress` for results.

Reconnects to a research run's live progress stream and blocks until the terminal `done` event, returning the same shape as `run_research_sse`: research run ID, synthesized report, citations, and plan iterations seen. Pass `last_event_id` to resume after a dropped connection without missing events. Disconnecting does not cancel the research; once the stream is gone, poll `get_research_run` instead.

Lists saved research runs with optional filtering by status, query text, and creation date range. Returns paginated run summaries plus a total count, sorted newest-first by default; pass the `cursor` from a previous response's `pagination.next_cursor` (with the same `sort_direction` used to generate it) to page through further results.

Retrieves one saved research run by ID: its status, quick and deep results, research plan, gathered evidence, and iteration count. `error` here is the run's own terminal outcome (why it failed or was cancelled), not an error from the underlying content or search providers.

Cancels a running research run by ID. This call is idempotent: calling it again on an already-terminal run still returns 200 with `cancelled: false` and the run's actual current status, instead of an error.

Lists Tetra browser session usage for the authenticated user — duration, data transfer, mode, and status for each session — with page-based pagination and optional filtering by session ID, status, and time range.

Creates a remote browser session and returns CDP connection details — connect via Playwright's `connect_over_cdp` or any CDP client at the returned `cdp_url`. Egresses through the TinyFish residential proxy in the US by default, pinned to one exit IP for the life of the session; pass `proxy_config` to use a different TinyFish proxy country or bring your own. Call `terminate_browser_session` with the returned `session_id` to release the session early instead of waiting for the inactivity timeout.

DESTRUCTIVE — REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. Immediately terminates a remote browser session, releasing its resources instead of waiting for its inactivity timeout to expire. This ends the live CDP connection and any in-progress browser activity on that session — it cannot be resumed, only replaced by creating a new session with create_browser_session. Idempotent: calling it again on an already-ended session still returns success rather than an error. NEVER call this tool autonomously or as part of an automated flow. You MUST stop, tell the user exactly which session will be terminated, and wait for their explicit written confirmation before proceeding.