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 Profile to stealth for anti-detection, and enable the Tetra proxy with a country when the page is geo-restricted.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.
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
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.
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.
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.
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.
Run a TinyFish web agent against a website and wait for it to finish, returning the structured result it extracted
Parameter Type Required Description urlstring Yes Target website URL the agent starts on goalstring Yes Natural-language description of what to accomplish on the website browserProfilestring No Browser engine: "lite" (standard) or "stealth" (anti-detection) agentModestring No Agent behavior: "default" or "strict" (fail fast) maxStepsnumber No Maximum tool-call steps before the agent stops (1-500, default 150) outputSchemajson No JSON Schema draft-07 contract the run result must satisfy proxyEnabledboolean No Route the run through TinyFish’s Tetra proxy proxyCountryCodestring No Proxy country: US, GB, CA, DE, FR, JP, or AU useVaultboolean No Let the run use credentials from the connected TinyFish vault credentialItemIdsstring No Comma-separated vault credential URIs to scope the run to apiKeystring Yes TinyFish API key
Parameter Type Description runIdstring Run identifier statusstring Final run status: COMPLETED or FAILED startedAtstring ISO 8601 timestamp when the run started finishedAtstring ISO 8601 timestamp when the run finished numOfStepsnumber Steps the agent took resultjson Structured data the agent extracted, null when the run failed schemaValidationobject 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 errorobject 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
Queue a TinyFish web agent run and return its run ID immediately, without waiting for the automation to finish
Parameter Type Required Description urlstring Yes Target website URL the agent starts on goalstring Yes Natural-language description of what to accomplish on the website browserProfilestring No Browser engine: "lite" (standard) or "stealth" (anti-detection) agentModestring No Agent behavior: "default" or "strict" (fail fast) maxStepsnumber No Maximum tool-call steps before the agent stops (1-500, default 150) outputSchemajson No JSON Schema draft-07 contract the run result must satisfy proxyEnabledboolean No Route the run through TinyFish’s Tetra proxy proxyCountryCodestring No Proxy country: US, GB, CA, DE, FR, JP, or AU useVaultboolean No Let the run use credentials from the connected TinyFish vault credentialItemIdsstring No Comma-separated vault credential URIs to scope the run to apiKeystring Yes TinyFish API key webhookUrlstring No HTTPS URL notified when the run completes, fails, or is cancelled
Parameter Type Description runIdstring Identifier of the queued run, used to poll or cancel it
Get the status, extracted result, and step history of a TinyFish automation run by its ID
Parameter Type Required Description runIdstring Yes Identifier of the run to look up apiKeystring Yes TinyFish API key
Parameter Type Description runIdstring Run identifier statusstring PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED goalstring Natural-language goal the run was given createdAtstring ISO 8601 timestamp when the run was created startedAtstring ISO 8601 timestamp when the run started executing finishedAtstring ISO 8601 timestamp when the run finished numOfStepsnumber Steps taken, null while the run is still in progress resultjson Structured data the agent extracted, null until the run succeeds schemaValidationobject 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 errorobject 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 streamingUrlstring Live browser view URL, available while the run is executing browserConfigobject Proxy settings the run executed with ↳ proxyEnabled boolean Whether a proxy was used ↳ proxyCountryCode string Proxy country code videoUrlstring Presigned recording URL, expires 15 minutes after it is issued stepsarray 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
Cancel a queued or in-progress TinyFish automation run by its ID
Parameter Type Required Description runIdstring Yes Identifier of the run to cancel apiKeystring Yes TinyFish API key
Parameter Type Description runIdstring Run identifier statusstring Status after the call: CANCELLED, or the terminal status the run already reached cancelledAtstring ISO 8601 timestamp of the cancellation, null when nothing was cancelled messagestring Context such as "Run already cancelled" or "Run already finished"
List TinyFish automation runs, optionally filtered by status, goal text, or creation date
Parameter Type Required Description statusstring No Filter by run status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED goalstring No Filter by goal text (case-insensitive partial match, max 500 characters) createdAfterstring No Only return runs created after this ISO 8601 timestamp createdBeforestring No Only return runs created before this ISO 8601 timestamp sortDirectionstring No Sort by creation time: "desc" (newest first, default) or "asc" limitnumber No Maximum runs to return (1-100, default 20) cursorstring No Pagination cursor returned by a previous call apiKeystring Yes TinyFish API key
Parameter Type Description runsarray 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 totalnumber Total runs matching the filters nextCursorstring Cursor for the next page, null when there are no more results hasMoreboolean Whether more results follow this page
Search the web with TinyFish and get ranked results with titles, snippets, and URLs
Parameter Type Required Description querystring Yes Search query locationstring No Country code for geo-targeted results, such as US languagestring No Language code for the results, such as en apiKeystring Yes TinyFish API key
Parameter Type Description querystring Query that was executed resultsarray 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 totalResultsnumber Number of results returned
Fetch up to 10 URLs with TinyFish, rendering JavaScript when needed, and return clean extracted content
Parameter Type Required Description urlsstring Yes Comma-separated list of 1-10 URLs to fetch formatstring No Extraction format: "markdown" (default), "html", or "json" linksboolean No Also return every outbound link found on each page imageLinksboolean No Also return every image URL found on each page apiKeystring Yes TinyFish API key
Parameter Type Description resultsarray 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 errorsarray URLs that failed. A per-URL failure never fails the whole request ↳ url string URL that failed ↳ error string Why the fetch failed
List the credentials available from password managers connected to TinyFish, with the URIs an agent run can be scoped to
Parameter Type Required Description apiKeystring Yes TinyFish API key
Parameter Type Description itemsarray 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