Skip to content
Try for free
On this page

Integrations

TinyFish

Automate and read the live web

Use TinyFish to run a browser agent from a starting URL and natural-language goal, search the web, or fetch rendered page content.

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 browser tasks: Navigate portals and retrieve data when the site is reachable and the agent has the required access.
  • Validate structured results: Supply a JSON Schema in Output Schema and inspect schemaValidation for mismatches before trusting the output.
  • Configure browser access: Switch Browser Engine to stealth when the site requires the stealth engine, 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.
  • Use vault credentials: 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 — rather than returning secret values in the listing. The remote agent uses the selected credentials during its run.
  • 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.
  • Gather web sources: 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 stepRun Agent
Kick off a long automation and check on it laterStart Agent Run, then Get Run
Stop a queued or in-flight automationCancel Run
Find runs you did not record the ID forList Runs
Get ranked web results for a querySearch
Read specific pages as clean textFetch URLs
Find the credential URI to scope a run toList 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

When hosted keys are enabled for the deployment, Run Agent, Search, and Fetch URLs can use Sim’s TinyFish key, metered to the workspace. Agent runs are billed per step; Search and Fetch currently have no provider usage charge. Check TinyFish pricing for current rates and limits. You can bring your own key in Settings → API Keys to bill TinyFish directly instead.

Start Agent Run, Get Run, Cancel Run, List Runs, List Vault Items, and List Browser Profiles 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.

Use the block

Give a web agent a natural-language goal and let it drive a real browser on supported, reachable sites, 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

Inputs and outputs

Input

ParameterTypeRequiredDescription
urlstringYesTarget website URL the agent starts on
goalstringYesNatural-language description of what to accomplish on the website
browserProfilestringNoBrowser engine: "lite" (standard) or "stealth" (anti-detection). Not a Browser Context Profile — use useProfile for saved logins
agentModestringNoAgent behavior: "default" or "strict" (fail fast)
maxStepsnumberNoMaximum tool-call steps before the agent stops (1-500, default 150)
maxDurationSecondsnumberNoMaximum 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
outputSchemajsonNoJSON Schema draft-07 contract the run result must satisfy
proxyEnabledbooleanNoRoute the run through TinyFish’s Tetra proxy
proxyCountryCodestringNoProxy country: US, GB, CA, DE, FR, JP, or AU
useVaultbooleanNoLet the run use credentials from the connected TinyFish vault
credentialItemIdsstringNoComma-separated vault credential URIs to scope the run to
useProfilebooleanNoStart the run from a saved Browser Context Profile, reusing the logged-in session stored in it
profileIdstringNoBrowser Context Profile to start from, such as "prof_abc123". Requires useProfile; omit to use the account default
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
runIdstringRun identifier
statusstringFinal run status: COMPLETED or FAILED
startedAtstringISO 8601 timestamp when the run started
finishedAtstringISO 8601 timestamp when the run finished
numOfStepsnumberSteps the agent took
resultjsonStructured data the agent extracted, null when the run failed
schemaValidationobjectValidation of the result against the requested output schema
↳ validbooleanWhether the result matched the requested output schema
↳ rePromptAttemptsnumberNumber of schema-repair re-prompts TinyFish performed
↳ errorsarrayFields that did not match the requested schema
↳ pathstringPath to the failing field
↳ expectedstringExpected type or constraint
↳ receivedstringType actually returned
↳ messagestringValidation error message
errorobjectWhy the run failed, null when it succeeded. Branch on category to decide whether to retry
↳ codestringMachine-readable error code
↳ messagestringWhy the run failed
↳ categorystringSYSTEM_FAILURE (retry), AGENT_FAILURE (fix the goal), BILLING_FAILURE (add credits), or UNKNOWN
↳ retryAfternumberSuggested retry delay in seconds, null when not retryable
↳ helpUrlstringTroubleshooting documentation URL
↳ helpMessagestringHuman-readable guidance
profileHintobjectPresent when TinyFish believes a Browser Context Profile would fix this failed run, such as one that stopped at a login wall
↳ messagestringWhy a Browser Context Profile would help this run
↳ setupUrlstringPath on the TinyFish dashboard that sets up a profile for the blocked domain
↳ reasonstringauth_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

Inputs and outputs

Input

ParameterTypeRequiredDescription
urlstringYesTarget website URL the agent starts on
goalstringYesNatural-language description of what to accomplish on the website
browserProfilestringNoBrowser engine: "lite" (standard) or "stealth" (anti-detection). Not a Browser Context Profile — use useProfile for saved logins
agentModestringNoAgent behavior: "default" or "strict" (fail fast)
maxStepsnumberNoMaximum tool-call steps before the agent stops (1-500, default 150)
maxDurationSecondsnumberNoMaximum 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
outputSchemajsonNoJSON Schema draft-07 contract the run result must satisfy
proxyEnabledbooleanNoRoute the run through TinyFish’s Tetra proxy
proxyCountryCodestringNoProxy country: US, GB, CA, DE, FR, JP, or AU
useVaultbooleanNoLet the run use credentials from the connected TinyFish vault
credentialItemIdsstringNoComma-separated vault credential URIs to scope the run to
useProfilebooleanNoStart the run from a saved Browser Context Profile, reusing the logged-in session stored in it
profileIdstringNoBrowser Context Profile to start from, such as "prof_abc123". Requires useProfile; omit to use the account default
apiKeystringYesTinyFish API key
webhookUrlstringNoHTTPS URL notified when the run completes, fails, or is cancelled

Output

ParameterTypeDescription
runIdstringIdentifier 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

Inputs and outputs

Input

ParameterTypeRequiredDescription
runIdstringYesIdentifier of the run to look up
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
runIdstringRun identifier
statusstringPENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
goalstringNatural-language goal the run was given
createdAtstringISO 8601 timestamp when the run was created
startedAtstringISO 8601 timestamp when the run started executing
finishedAtstringISO 8601 timestamp when the run finished
numOfStepsnumberSteps taken, null while the run is still in progress
resultjsonStructured data the agent extracted, null until the run succeeds
schemaValidationobjectValidation of the result against the requested output schema
↳ validbooleanWhether the result matched the requested output schema
↳ rePromptAttemptsnumberNumber of schema-repair re-prompts TinyFish performed
↳ errorsarrayFields that did not match the requested schema
↳ pathstringPath to the failing field
↳ expectedstringExpected type or constraint
↳ receivedstringType actually returned
↳ messagestringValidation error message
errorobjectFailure details, null while the run is pending or succeeded
↳ codestringMachine-readable error code
↳ messagestringWhy the run failed
↳ categorystringSYSTEM_FAILURE (retry), AGENT_FAILURE (fix the goal), BILLING_FAILURE (add credits), or UNKNOWN
↳ retryAfternumberSuggested retry delay in seconds, null when not retryable
↳ helpUrlstringTroubleshooting documentation URL
↳ helpMessagestringHuman-readable guidance
streamingUrlstringLive browser view URL, available while the run is executing
browserConfigobjectProxy settings the run executed with
↳ proxyEnabledbooleanWhether a proxy was used
↳ proxyCountryCodestringProxy country code
profileAttachedbooleanWhether the run actually started from a Browser Context Profile, null when the API omits it — treat null as unknown rather than as false
profileIdstringBrowser 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
profileHintobjectPresent when TinyFish believes a Browser Context Profile would fix this failed run
↳ messagestringWhy a Browser Context Profile would help this run
↳ setupUrlstringPath on the TinyFish dashboard that sets up a profile for the blocked domain
↳ reasonstringauth_wall (the run hit a login) or bot_challenge (the site blocked automation)
videoUrlstringPresigned recording URL, expires 15 minutes after it is issued
stepsarraySteps the agent took during the run
↳ idstringStep identifier
↳ timestampstringISO 8601 timestamp of the step
↳ statusstringStatus of the run at this step
↳ actionstringAction the agent took
↳ durationstringTime the step took

TinyFish Cancel Run

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

Inputs and outputs

Input

ParameterTypeRequiredDescription
runIdstringYesIdentifier of the run to cancel
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
runIdstringRun identifier
statusstringStatus after the call: CANCELLED, or the terminal status the run already reached
cancelledAtstringISO 8601 timestamp of the cancellation, null when nothing was cancelled
messagestringContext 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

Inputs and outputs

Input

ParameterTypeRequiredDescription
statusstringNoFilter by run status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
goalstringNoFilter by goal text (case-insensitive partial match, max 500 characters)
createdAfterstringNoOnly return runs created after this ISO 8601 timestamp
createdBeforestringNoOnly return runs created before this ISO 8601 timestamp
sortDirectionstringNoSort by creation time: "desc" (newest first, default) or "asc"
limitnumberNoMaximum runs to return (1-100, default 20)
cursorstringNoPagination cursor returned by a previous call
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
runsarrayRuns matching the filters, newest first by default
↳ runIdstringRun identifier
↳ statusstringPENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
↳ goalstringNatural-language goal the run was given
↳ createdAtstringISO 8601 timestamp when the run was created
↳ startedAtstringISO 8601 timestamp when the run started executing
↳ finishedAtstringISO 8601 timestamp when the run finished
↳ numOfStepsnumberSteps taken, null while the run is still in progress
↳ resultjsonStructured data the agent extracted, null until the run succeeds
↳ schemaValidationobjectValidation of the result against the requested output schema
↳ validbooleanWhether the result matched the requested output schema
↳ rePromptAttemptsnumberNumber of schema-repair re-prompts TinyFish performed
↳ errorsarrayFields that did not match the requested schema
↳ pathstringPath to the failing field
↳ expectedstringExpected type or constraint
↳ receivedstringType actually returned
↳ messagestringValidation error message
↳ errorobjectFailure details, null while the run is pending or succeeded
↳ codestringMachine-readable error code
↳ messagestringWhy the run failed
↳ categorystringSYSTEM_FAILURE (retry), AGENT_FAILURE (fix the goal), BILLING_FAILURE (add credits), or UNKNOWN
↳ retryAfternumberSuggested retry delay in seconds, null when not retryable
↳ helpUrlstringTroubleshooting documentation URL
↳ helpMessagestringHuman-readable guidance
↳ streamingUrlstringLive browser view URL, available while the run is executing
↳ browserConfigobjectProxy settings the run executed with
↳ proxyEnabledbooleanWhether a proxy was used
↳ proxyCountryCodestringProxy country code
↳ profileAttachedbooleanWhether the run actually started from a Browser Context Profile, null when the API omits it — treat null as unknown rather than as false
↳ profileIdstringBrowser 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
↳ profileHintobjectPresent when TinyFish believes a Browser Context Profile would fix this failed run
↳ messagestringWhy a Browser Context Profile would help this run
↳ setupUrlstringPath on the TinyFish dashboard that sets up a profile for the blocked domain
↳ reasonstringauth_wall (the run hit a login) or bot_challenge (the site blocked automation)
totalnumberTotal runs matching the filters
nextCursorstringCursor for the next page, null when there are no more results
hasMorebooleanWhether more results follow this page

TinyFish Search

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

Inputs and outputs

Input

ParameterTypeRequiredDescription
querystringYesSearch query
locationstringNoCountry code for geo-targeted results, such as US
languagestringNoLanguage code for the results, such as en
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
querystringQuery that was executed
resultsarrayRanked search results
↳ positionnumberRank in the result list
↳ siteNamestringSite the result came from
↳ snippetstringText snippet from the page
↳ titlestringPage title
↳ urlstringResult URL
totalResultsnumberNumber of results returned

TinyFish Fetch

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

Inputs and outputs

Input

ParameterTypeRequiredDescription
urlsstringYesComma-separated list of 1-10 URLs to fetch
formatstringNoExtraction format: "markdown" (default), "html", or "json"
linksbooleanNoAlso return every outbound link found on each page
imageLinksbooleanNoAlso return every image URL found on each page
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
resultsarraySuccessfully fetched pages
↳ urlstringURL that was requested
↳ finalUrlstringURL after redirects
↳ titlestringPage title
↳ descriptionstringMeta description
↳ languagestringDetected language code
↳ formatstringFormat of the extracted content
↳ textjsonExtracted content — a string for markdown and html, a document tree for json
↳ authorstringPage author
↳ publishedDatestringPublished date
↳ linksarrayOutbound links, only when links was requested
↳ imageLinksarrayImage URLs, only when image links were requested
↳ latencyMsnumberFetch latency in ms
errorsarrayURLs that failed. A per-URL failure never fails the whole request
↳ urlstringURL that failed
↳ errorstringWhy 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

Inputs and outputs

Input

ParameterTypeRequiredDescription
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
itemsarrayCredentials available to automation runs
↳ itemIdstringCredential URI, used as a Vault Credential URI on a run
↳ connectionIdstringIdentifier of the vault connection it came from
↳ labelstringCredential name, such as "Amazon Login"
↳ vaultNamestringVault the credential lives in
↳ domainsarrayDomains the credential applies to
↳ fieldMetadataarrayFields the credential carries, without their values
↳ fieldIdstringField identifier
↳ labelstringField name
↳ typestringSTRING, CONCEALED, or OTP
↳ hasTotpbooleanWhether 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

Inputs and outputs

Input

ParameterTypeRequiredDescription
apiKeystringYesTinyFish API key

Output

ParameterTypeDescription
profilesarrayBrowser Context Profiles an agent run can start from
↳ profileIdstringProfile identifier, used as the Browser Profile ID on a run
↳ namestringProfile name, such as "Salesforce Production"
↳ proxyCountryCodestringCountry the profile proxies through, null when it has no proxy
↳ fingerprintSeedstringSeed for the browser fingerprint the profile replays, null when the API omits it
↳ domainCountnumberHow many domains the profile holds saved state for, null when the API omits it. Zero means it was created but never logged into
↳ createdAtstringISO 8601 timestamp when the profile was created, null when the API omits it
↳ updatedAtstringISO 8601 timestamp when the profile was last saved, null when the API omits it
↳ isDefaultbooleanWhether runs with no Browser Profile ID use this one, null when the API omits it
Was this helpful?
Suggest an edit