# TinyFish (/integrations/tinyfish)

Use [TinyFish](https://www.tinyfish.ai/) 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 \[#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 \[#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 \[#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](https://www.tinyfish.ai/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 \[#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 \[#usage-instructions]

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 \[#actions]

### TinyFish Run Agent \[#tinyfish-run-agent]

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

#### Input \[#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 \[#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 \[#tinyfish-start-agent-run]

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

#### Input \[#input-1]

| 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 \[#output-1]

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

### TinyFish Get Run \[#tinyfish-get-run]

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

#### Input \[#input-2]

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

#### Output \[#output-2]

| 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 \[#tinyfish-cancel-run]

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

#### Input \[#input-3]

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

#### Output \[#output-3]

| 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 \[#tinyfish-list-runs]

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

#### Input \[#input-4]

| 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 \[#output-4]

| 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 \[#tinyfish-search]

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

#### Input \[#input-5]

| 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 \[#output-5]

| 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 \[#tinyfish-fetch]

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

#### Input \[#input-6]

| 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 \[#output-6]

| 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 \[#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 \[#input-7]

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

#### Output \[#output-7]

| 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 \[#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 \[#input-8]

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

#### Output \[#output-8]

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