TinyFish

TinyFish is web infrastructure for AI agents. Instead of maintaining a scraper per site, you give a TinyFish web agent a natural-language goal and a starting URL, and it drives a real browser — clicking, typing, paginating, logging in — until the goal is met, then returns what it found as structured JSON.

TinyFish exposes three surfaces through this block:

Agent — natural-language browser automation on live websites. Charged per step from a prepaid wallet.
Search — ranked web results with titles, snippets, and URLs. Free.
Fetch — up to 10 URLs at a time rendered and extracted as clean markdown, HTML, or a JSON document tree. Free.

With TinyFish in Sim, you can:

Automate any site, API or not: Log into vendor portals, legacy ERPs, and internal tools that never shipped an API, and pull the data out.
Get typed results, not scraped HTML: Supply a JSON Schema in Output Schema and TinyFish holds the agent to it, re-prompting on mismatch and reporting every field that did not match in schemaValidation.
Survive bot detection: Switch Browser Engine to stealth for anti-detection, and enable the Tetra proxy with a country when the page is geo-restricted.
Stay logged in between runs: Enable Use Browser Profile to start a run from a Browser Context Profile — saved browser state you log into once on TinyFish. List Browser Profiles returns the ids to choose from; leaving the id empty uses your default profile. Pair it with the vault so an expired session can be repaired.
Log in safely: Connect a password manager to TinyFish's vault, then enable Use Vault Credentials and scope a run to specific credential URIs. List Vault Items returns those URIs as display-safe metadata — labels, domains, field names — so credentials never travel through the workflow.
Run work that outlives a step: Start Agent Run queues an automation and returns a run ID immediately; Get Run, Cancel Run, and List Runs track it afterwards, and a webhook URL can notify you on completion.
Read the live web cheaply: Pair Search and Fetch URLs to gather current sources before an agent writes or answers.

Choosing an operation

You want to…	Use
Get an answer back in the same workflow step	Run Agent
Kick off a long automation and check on it later	Start Agent Run, then Get Run
Stop a queued or in-flight automation	Cancel Run
Find runs you did not record the ID for	List Runs
Get ranked web results for a query	Search
Read specific pages as clean text	Fetch URLs
Find the credential URI to scope a run to	List Vault Items

Writing a good goal

The goal is handed to the agent's model verbatim, so it behaves like a prompt. Name the destination, the data, and the stopping condition — "open the pricing page and collect every plan name and monthly price" beats "get pricing". Start the run as close to the target page as you can: every navigation the URL saves is a step you are not billed for. Use Agent Mode strict when the run is a test that should fail loudly rather than improvise.

API key and hosted keys

On Sim's hosted platform, Run Agent, Search, and Fetch URLs run on Sim's TinyFish key by default, metered to your workspace — Agent runs are billed per step, Search and Fetch are free. You can bring your own key in Settings → API Keys to bill TinyFish directly instead.

Start Agent Run, Get Run, Cancel Run, List Runs, and List Vault Items always require your own key. An async run accrues its charge after the request returns, so there is nothing for Sim to meter at call time.

Errors

A failed automation comes back as HTTP 200 with the failure inside the run's own error object, so read status rather than assuming success. The category tells you what to do: AGENT_FAILURE means the goal or the site needs attention, SYSTEM_FAILURE is worth retrying after retryAfter seconds, and BILLING_FAILURE means the TinyFish wallet is empty. All of that is on the block's error output, so a workflow can branch on it without parsing a message string.

Usage Instructions

Integrate TinyFish into the workflow. Give a web agent a natural-language goal and let it drive a real browser on any site, queue and track long-running automations, search the web, and fetch pages as clean markdown.

Actions

TinyFish Run Agent

Run a TinyFish web agent against a website and wait for it to finish, returning the structured result it extracted

Input

Parameter	Type	Required	Description
`url`	string	Yes	Target website URL the agent starts on
`goal`	string	Yes	Natural-language description of what to accomplish on the website
`browserProfile`	string	No	Browser engine: "lite" (standard) or "stealth" (anti-detection). Not a Browser Context Profile — use useProfile for saved logins
`agentMode`	string	No	Agent behavior: "default" or "strict" (fail fast)
`maxSteps`	number	No	Maximum tool-call steps before the agent stops (1-500, default 150)
`maxDurationSeconds`	number	No	Maximum wall-clock seconds before the agent stops. Unlimited by default, so a run stalled on a slow page is only bounded by the step cap
`outputSchema`	json	No	JSON Schema draft-07 contract the run result must satisfy
`proxyEnabled`	boolean	No	Route the run through TinyFish’s Tetra proxy
`proxyCountryCode`	string	No	Proxy country: US, GB, CA, DE, FR, JP, or AU
`useVault`	boolean	No	Let the run use credentials from the connected TinyFish vault
`credentialItemIds`	string	No	Comma-separated vault credential URIs to scope the run to
`useProfile`	boolean	No	Start the run from a saved Browser Context Profile, reusing the logged-in session stored in it
`profileId`	string	No	Browser Context Profile to start from, such as "prof_abc123". Requires useProfile; omit to use the account default
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`runId`	string	Run identifier
`status`	string	Final run status: COMPLETED or FAILED
`startedAt`	string	ISO 8601 timestamp when the run started
`finishedAt`	string	ISO 8601 timestamp when the run finished
`numOfSteps`	number	Steps the agent took
`result`	json	Structured data the agent extracted, null when the run failed
`schemaValidation`	object	Validation of the result against the requested output schema
↳ `valid`	boolean	Whether the result matched the requested output schema
↳ `rePromptAttempts`	number	Number of schema-repair re-prompts TinyFish performed
↳ `errors`	array	Fields that did not match the requested schema
↳ `path`	string	Path to the failing field
↳ `expected`	string	Expected type or constraint
↳ `received`	string	Type actually returned
↳ `message`	string	Validation error message
`error`	object	Why the run failed, null when it succeeded. Branch on category to decide whether to retry
↳ `code`	string	Machine-readable error code
↳ `message`	string	Why the run failed
↳ `category`	string	SYSTEM_FAILURE (retry), AGENT_FAILURE (fix the goal), BILLING_FAILURE (add credits), or UNKNOWN
↳ `retryAfter`	number	Suggested retry delay in seconds, null when not retryable
↳ `helpUrl`	string	Troubleshooting documentation URL
↳ `helpMessage`	string	Human-readable guidance
`profileHint`	object	Present when TinyFish believes a Browser Context Profile would fix this failed run, such as one that stopped at a login wall
↳ `message`	string	Why a Browser Context Profile would help this run
↳ `setupUrl`	string	Path on the TinyFish dashboard that sets up a profile for the blocked domain
↳ `reason`	string	auth_wall (the run hit a login) or bot_challenge (the site blocked automation)

TinyFish Start Agent Run

Queue a TinyFish web agent run and return its run ID immediately, without waiting for the automation to finish

Input

Parameter	Type	Required	Description
`url`	string	Yes	Target website URL the agent starts on
`goal`	string	Yes	Natural-language description of what to accomplish on the website
`browserProfile`	string	No	Browser engine: "lite" (standard) or "stealth" (anti-detection). Not a Browser Context Profile — use useProfile for saved logins
`agentMode`	string	No	Agent behavior: "default" or "strict" (fail fast)
`maxSteps`	number	No	Maximum tool-call steps before the agent stops (1-500, default 150)
`maxDurationSeconds`	number	No	Maximum wall-clock seconds before the agent stops. Unlimited by default, so a run stalled on a slow page is only bounded by the step cap
`outputSchema`	json	No	JSON Schema draft-07 contract the run result must satisfy
`proxyEnabled`	boolean	No	Route the run through TinyFish’s Tetra proxy
`proxyCountryCode`	string	No	Proxy country: US, GB, CA, DE, FR, JP, or AU
`useVault`	boolean	No	Let the run use credentials from the connected TinyFish vault
`credentialItemIds`	string	No	Comma-separated vault credential URIs to scope the run to
`useProfile`	boolean	No	Start the run from a saved Browser Context Profile, reusing the logged-in session stored in it
`profileId`	string	No	Browser Context Profile to start from, such as "prof_abc123". Requires useProfile; omit to use the account default
`apiKey`	string	Yes	TinyFish API key
`webhookUrl`	string	No	HTTPS URL notified when the run completes, fails, or is cancelled

Output

Parameter	Type	Description
`runId`	string	Identifier of the queued run, used to poll or cancel it

TinyFish Get Run

Get the status, extracted result, and step history of a TinyFish automation run by its ID

Input

Parameter	Type	Required	Description
`runId`	string	Yes	Identifier of the run to look up
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`runId`	string	Run identifier
`status`	string	PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
`goal`	string	Natural-language goal the run was given
`createdAt`	string	ISO 8601 timestamp when the run was created
`startedAt`	string	ISO 8601 timestamp when the run started executing
`finishedAt`	string	ISO 8601 timestamp when the run finished
`numOfSteps`	number	Steps taken, null while the run is still in progress
`result`	json	Structured data the agent extracted, null until the run succeeds
`schemaValidation`	object	Validation of the result against the requested output schema
↳ `valid`	boolean	Whether the result matched the requested output schema
↳ `rePromptAttempts`	number	Number of schema-repair re-prompts TinyFish performed
↳ `errors`	array	Fields that did not match the requested schema
↳ `path`	string	Path to the failing field
↳ `expected`	string	Expected type or constraint
↳ `received`	string	Type actually returned
↳ `message`	string	Validation error message
`error`	object	Failure details, null while the run is pending or succeeded
↳ `code`	string	Machine-readable error code
↳ `message`	string	Why the run failed
↳ `category`	string	SYSTEM_FAILURE (retry), AGENT_FAILURE (fix the goal), BILLING_FAILURE (add credits), or UNKNOWN
↳ `retryAfter`	number	Suggested retry delay in seconds, null when not retryable
↳ `helpUrl`	string	Troubleshooting documentation URL
↳ `helpMessage`	string	Human-readable guidance
`streamingUrl`	string	Live browser view URL, available while the run is executing
`browserConfig`	object	Proxy settings the run executed with
↳ `proxyEnabled`	boolean	Whether a proxy was used
↳ `proxyCountryCode`	string	Proxy country code
`profileAttached`	boolean	Whether the run actually started from a Browser Context Profile, null when the API omits it — treat null as unknown rather than as false
`profileId`	string	Browser Context Profile the run attached. Null covers both no profile and a payload that omitted the field, so read profileAttached alongside it rather than reading null as proof
`profileHint`	object	Present when TinyFish believes a Browser Context Profile would fix this failed run
↳ `message`	string	Why a Browser Context Profile would help this run
↳ `setupUrl`	string	Path on the TinyFish dashboard that sets up a profile for the blocked domain
↳ `reason`	string	auth_wall (the run hit a login) or bot_challenge (the site blocked automation)
`videoUrl`	string	Presigned recording URL, expires 15 minutes after it is issued
`steps`	array	Steps the agent took during the run
↳ `id`	string	Step identifier
↳ `timestamp`	string	ISO 8601 timestamp of the step
↳ `status`	string	Status of the run at this step
↳ `action`	string	Action the agent took
↳ `duration`	string	Time the step took

TinyFish Cancel Run

Cancel a queued or in-progress TinyFish automation run by its ID

Input

Parameter	Type	Required	Description
`runId`	string	Yes	Identifier of the run to cancel
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`runId`	string	Run identifier
`status`	string	Status after the call: CANCELLED, or the terminal status the run already reached
`cancelledAt`	string	ISO 8601 timestamp of the cancellation, null when nothing was cancelled
`message`	string	Context such as "Run already cancelled" or "Run already finished"

TinyFish List Runs

List TinyFish automation runs, optionally filtered by status, goal text, or creation date

Input

Parameter	Type	Required	Description
`status`	string	No	Filter by run status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
`goal`	string	No	Filter by goal text (case-insensitive partial match, max 500 characters)
`createdAfter`	string	No	Only return runs created after this ISO 8601 timestamp
`createdBefore`	string	No	Only return runs created before this ISO 8601 timestamp
`sortDirection`	string	No	Sort by creation time: "desc" (newest first, default) or "asc"
`limit`	number	No	Maximum runs to return (1-100, default 20)
`cursor`	string	No	Pagination cursor returned by a previous call
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`runs`	array	Runs matching the filters, newest first by default
↳ `runId`	string	Run identifier
↳ `status`	string	PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
↳ `goal`	string	Natural-language goal the run was given
↳ `createdAt`	string	ISO 8601 timestamp when the run was created
↳ `startedAt`	string	ISO 8601 timestamp when the run started executing
↳ `finishedAt`	string	ISO 8601 timestamp when the run finished
↳ `numOfSteps`	number	Steps taken, null while the run is still in progress
↳ `result`	json	Structured data the agent extracted, null until the run succeeds
↳ `schemaValidation`	object	Validation of the result against the requested output schema
↳ `valid`	boolean	Whether the result matched the requested output schema
↳ `rePromptAttempts`	number	Number of schema-repair re-prompts TinyFish performed
↳ `errors`	array	Fields that did not match the requested schema
↳ `path`	string	Path to the failing field
↳ `expected`	string	Expected type or constraint
↳ `received`	string	Type actually returned
↳ `message`	string	Validation error message
↳ `error`	object	Failure details, null while the run is pending or succeeded
↳ `code`	string	Machine-readable error code
↳ `message`	string	Why the run failed
↳ `category`	string	SYSTEM_FAILURE (retry), AGENT_FAILURE (fix the goal), BILLING_FAILURE (add credits), or UNKNOWN
↳ `retryAfter`	number	Suggested retry delay in seconds, null when not retryable
↳ `helpUrl`	string	Troubleshooting documentation URL
↳ `helpMessage`	string	Human-readable guidance
↳ `streamingUrl`	string	Live browser view URL, available while the run is executing
↳ `browserConfig`	object	Proxy settings the run executed with
↳ `proxyEnabled`	boolean	Whether a proxy was used
↳ `proxyCountryCode`	string	Proxy country code
↳ `profileAttached`	boolean	Whether the run actually started from a Browser Context Profile, null when the API omits it — treat null as unknown rather than as false
↳ `profileId`	string	Browser Context Profile the run attached. Null covers both no profile and a payload that omitted the field, so read profileAttached alongside it rather than reading null as proof
↳ `profileHint`	object	Present when TinyFish believes a Browser Context Profile would fix this failed run
↳ `message`	string	Why a Browser Context Profile would help this run
↳ `setupUrl`	string	Path on the TinyFish dashboard that sets up a profile for the blocked domain
↳ `reason`	string	auth_wall (the run hit a login) or bot_challenge (the site blocked automation)
`total`	number	Total runs matching the filters
`nextCursor`	string	Cursor for the next page, null when there are no more results
`hasMore`	boolean	Whether more results follow this page

TinyFish Search

Search the web with TinyFish and get ranked results with titles, snippets, and URLs

Input

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`location`	string	No	Country code for geo-targeted results, such as US
`language`	string	No	Language code for the results, such as en
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`query`	string	Query that was executed
`results`	array	Ranked search results
↳ `position`	number	Rank in the result list
↳ `siteName`	string	Site the result came from
↳ `snippet`	string	Text snippet from the page
↳ `title`	string	Page title
↳ `url`	string	Result URL
`totalResults`	number	Number of results returned

TinyFish Fetch

Fetch up to 10 URLs with TinyFish, rendering JavaScript when needed, and return clean extracted content

Input

Parameter	Type	Required	Description
`urls`	string	Yes	Comma-separated list of 1-10 URLs to fetch
`format`	string	No	Extraction format: "markdown" (default), "html", or "json"
`links`	boolean	No	Also return every outbound link found on each page
`imageLinks`	boolean	No	Also return every image URL found on each page
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`results`	array	Successfully fetched pages
↳ `url`	string	URL that was requested
↳ `finalUrl`	string	URL after redirects
↳ `title`	string	Page title
↳ `description`	string	Meta description
↳ `language`	string	Detected language code
↳ `format`	string	Format of the extracted content
↳ `text`	json	Extracted content — a string for markdown and html, a document tree for json
↳ `author`	string	Page author
↳ `publishedDate`	string	Published date
↳ `links`	array	Outbound links, only when links was requested
↳ `imageLinks`	array	Image URLs, only when image links were requested
↳ `latencyMs`	number	Fetch latency in ms
`errors`	array	URLs that failed. A per-URL failure never fails the whole request
↳ `url`	string	URL that failed
↳ `error`	string	Why the fetch failed

TinyFish List Vault Items

List the credentials available from password managers connected to TinyFish, with the URIs an agent run can be scoped to

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`items`	array	Credentials available to automation runs
↳ `itemId`	string	Credential URI, used as a Vault Credential URI on a run
↳ `connectionId`	string	Identifier of the vault connection it came from
↳ `label`	string	Credential name, such as "Amazon Login"
↳ `vaultName`	string	Vault the credential lives in
↳ `domains`	array	Domains the credential applies to
↳ `fieldMetadata`	array	Fields the credential carries, without their values
↳ `fieldId`	string	Field identifier
↳ `label`	string	Field name
↳ `type`	string	STRING, CONCEALED, or OTP
↳ `hasTotp`	boolean	Whether the credential carries a TOTP secret

TinyFish List Browser Profiles

List the Browser Context Profiles saved on the TinyFish account, with the ids an agent run can start from to reuse a logged-in session

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	TinyFish API key

Output

Parameter	Type	Description
`profiles`	array	Browser Context Profiles an agent run can start from
↳ `profileId`	string	Profile identifier, used as the Browser Profile ID on a run
↳ `name`	string	Profile name, such as "Salesforce Production"
↳ `proxyCountryCode`	string	Country the profile proxies through, null when it has no proxy
↳ `fingerprintSeed`	string	Seed for the browser fingerprint the profile replays, null when the API omits it
↳ `domainCount`	number	How many domains the profile holds saved state for, null when the API omits it. Zero means it was created but never logged into
↳ `createdAt`	string	ISO 8601 timestamp when the profile was created, null when the API omits it
↳ `updatedAt`	string	ISO 8601 timestamp when the profile was last saved, null when the API omits it
↳ `isDefault`	boolean	Whether runs with no Browser Profile ID use this one, null when the API omits it

TinyFish

On this page