TinyFish
App · 25 actions
Send AI web agents to do tasks on real websites from a goal in plain words, search and read the web, write cited research reports, watch pages for changes and fill datasets from the web.
Actions
| Action | What it does |
|---|---|
| Cancel a web agent run | Stop an agent run started with 'Start a web agent run'. |
| Cancel research | Stop a research run that is still working. |
| Check a monitor now | Check a monitor's page or search now, outside its schedule, and get what it found. |
| Create a dataset | Describe a table in a sentence, such as "climbing gyms in Denver with their websites and day pass prices", and TinyFish plans its columns and fills it from the web in the background. |
| Create a page monitor | Have TinyFish read a page on a schedule and note what changed. |
| Create a topic monitor | Have TinyFish repeat a web search on a schedule and note new results. |
| Delete a dataset | Delete a dataset and its rows. |
| Delete a monitor | Delete a monitor and its schedule. |
| Get a dataset | Get a dataset: its columns, how many rows it has and whether it is still being filled. |
| Get a monitor | Get a monitor: what it watches, its schedule and whether it is running. |
| Get a web agent run | Get an agent run: whether it has finished, its result or error, and each step it took. |
| Get dataset rows | Get a dataset's rows in the order they were added, with its columns. |
| Get research | Get a research run: whether it has finished, its report and the sources it cites. |
| Get wallet balance | Get how much money is left in the TinyFish wallet and how it reloads. |
| List datasets | List the account's datasets, newest first. |
| List monitors | List every page and topic monitor on the account. |
| List research | List research runs, newest first, filtered by status, words or date. |
| List web agent runs | List agent runs, newest first, filtered by status, words in the goal or when they were created. |
| Pause or resume a monitor | Pause a monitor's scheduled checks, or resume them. |
| Read web pages | Read up to ten web pages and get each one's clean text, ready for an AI step, with its title and details. |
| Run a web agent | Send an AI agent to a website to do what the goal says, such as find information, fill in a form or collect a list, and wait for its result (up to 10 minutes). |
| Search the web | Search the web, news or research papers and get the ranked results with titles, snippets and links. |
| Start a web agent run | Start an AI agent on a website in the background and continue at once. |
| Start research | Have TinyFish research a question across many sources and write a report with citations, in the background. |
| Update a monitor | Rename a monitor, change what matters to it, or change its schedule. |
Cancel a web agent run
Stop an agent run started with 'Start a web agent run'. A run that has already finished is left as it is.
Inputs
- Agent run
run_idtextRequired - The run. Pick a recent one, or give its id from an earlier step.
Outputs
cancelledtrue/false- Whether it is now cancelled
cancelled_attext- When it was cancelled, if it was
messagetext- TinyFish's note, such as 'Run already finished'
run_idtext- The run
statustext- Its status now: CANCELLED, COMPLETED or FAILED
Example output
{
"cancelled": true,
"cancelled_at": "2026-11-01T10:30:55Z",
"message": "",
"run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "CANCELLED"
}Cancel research
Stop a research run that is still working.
Inputs
- Research run
research_run_idtextRequired - The research run. Pick a recent one, or give its id from an earlier step.
Outputs
cancelledtrue/false- Whether this cancelled it
research_run_idtext- The research run
statustext- Its status now
Example output
{
"cancelled": true,
"research_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "CANCELLED"
}Check a monitor now
Check a monitor's page or search now, outside its schedule, and get what it found. It costs the same as a scheduled check.
Inputs
- Monitor
monitor_idtextRequired - The monitor. Pick one, or give its id from an earlier step.
Outputs
checkobject- The check
countnumber- How many results
monitor_idtext- The monitor
resultslist- What it found: the page, or the search's results
Example output
{
"check": {
"created_at": "",
"errors": [],
"id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
"is_baseline": false,
"new_result_positions": [],
"query": "",
"result_count": 0,
"results": [
{
"author": null,
"description": null,
"final_url": "https://example.com/pricing",
"format": "markdown",
"language": "en",
"published_date": null,
"text": "# Pricing\nPro: $29/month",
"title": "Pricing",
"url": "https://example.com/pricing"
}
]
},
"count": 1,
"monitor_id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
"results": [
{
"author": null,
"description": null,
"final_url": "https://example.com/pricing",
"format": "markdown",
"language": "en",
"published_date": null,
"text": "# Pricing\nPro: $29/month",
"title": "Pricing",
"url": "https://example.com/pricing"
}
]
}Create a dataset
Describe a table in a sentence, such as "climbing gyms in Denver with their websites and day pass prices", and TinyFish plans its columns and fills it from the web in the background. Follow it with 'Get a dataset', or use the 'Dataset is filled' trigger.
Inputs
- What it holds
descriptiontextRequired - What the dataset should contain, in plain words.
- Rows
target_rowsnumber - How many rows to fill it to, 1 to 250.From 1 to 250.
- Start filling now
fill_nowtrue/false - On by default. Turn off to only plan its columns.
Outputs
datasetobject- The dataset
Example output
{
"dataset": {
"created_at": "2026-11-01T09:00:00Z",
"id": "6f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
"name": "Climbing gyms in Denver",
"row_count": 0,
"run": {
"error": "",
"finished_at": "2026-11-01T09:04:00Z",
"id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"started_at": "2026-11-01T09:00:01Z",
"status": "queued"
},
"spec": {
"columns": [
{
"is_primary_key": true,
"name": "name",
"type": "string"
},
{
"is_primary_key": false,
"name": "website",
"type": "url"
}
],
"description": "Climbing gyms in Denver with their websites",
"name": "Climbing gyms in Denver"
},
"status": "populating",
"target_rows": 20
}
}Create a page monitor
Have TinyFish read a page on a schedule and note what changed. Its first check is made at once. Each check costs half a cent.
Inputs
- Page
urltextRequired - The web address of the page to watch.
- How often
frequencytextRequired - How often TinyFish checks.One of:
hourly(Every hour),every_6_hours(Every 6 hours),daily(Every day),weekdays(Every weekday),weekly(Every week). - At
at_timetime - The time of day it checks, 9:00 by default. For every hour, only the minutes count.
- On
weekdaytext - The day of the week, for a weekly check.One of:
1(Monday (default)),2(Tuesday),3(Wednesday),4(Thursday),5(Friday),6(Saturday),0(Sunday). - Time zone
time_zonetext - The time zone of that time. UTC by default.
- Name
nametext - A name to know the monitor by, up to 100 characters.
- What matters
purposetext - The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.
- Text as
page_formattext - How each page's text comes back.One of:
markdown(Markdown (default)),html(Cleaned HTML),json(Structured document). - Include links
include_linkstrue/false - Also list every link on the page.
- Include image links
include_image_linkstrue/false - Also list the address of every image on the page.
Outputs
baselineobject- Its first check, kept to compare with
monitorobject- The new monitor
Example output
{
"baseline": {
"created_at": "",
"errors": [],
"id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
"is_baseline": true,
"new_result_positions": [],
"query": "",
"result_count": 0,
"results": [
{
"author": null,
"description": null,
"final_url": "https://example.com/pricing",
"format": "markdown",
"language": "en",
"published_date": null,
"text": "# Pricing\nPro: $29/month",
"title": "Pricing",
"url": "https://example.com/pricing"
}
]
},
"monitor": {
"config": {
"format": "markdown",
"image_links": false,
"links": false,
"query": "",
"recency_minutes": 0,
"result_limit": 0,
"url": "https://example.com/pricing"
},
"created_at": "2026-11-01 09:00:00",
"id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
"last_error": "",
"name": "Competitor pricing",
"schedule_cron": "CRON_TZ=America/New_York 0 9 * * *",
"status": "active",
"type": "fetch",
"updated_at": "2026-11-01 09:00:00",
"webhook_url": ""
}
}Create a topic monitor
Have TinyFish repeat a web search on a schedule and note new results. Its first search is made at once. Checks must be at least 30 minutes apart; each costs half a cent.
Inputs
- Search for
querytextRequired - The search to repeat.
- How often
frequencytextRequired - How often TinyFish checks.One of:
hourly(Every hour),every_6_hours(Every 6 hours),daily(Every day),weekdays(Every weekday),weekly(Every week). - At
at_timetime - The time of day it checks, 9:00 by default. For every hour, only the minutes count.
- On
weekdaytext - The day of the week, for a weekly check.One of:
1(Monday (default)),2(Tuesday),3(Wednesday),4(Thursday),5(Friday),6(Saturday),0(Sunday). - Time zone
time_zonetext - The time zone of that time. UTC by default.
- Name
nametext - A name to know the monitor by, up to 100 characters.
- What matters
purposetext - The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.
- Published within
published_withintext - Only results published this recently.One of:
60(The last hour),1440(The last day),10080(The last week),43200(The last 30 days). - Results to compare
result_limitnumber - How many results to compare each time, 1 to 10. TinyFish's default is 10.From 1 to 10.
Outputs
baselineobject- Its first check, kept to compare with
monitorobject- The new monitor
Example output
{
"baseline": {
"created_at": "",
"errors": [],
"id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
"is_baseline": false,
"new_result_positions": [],
"query": "new electric vehicle policies",
"result_count": 1,
"results": [
{
"position": 1,
"title": "New electric vehicle policy",
"url": "https://example.gov/ev-policy"
}
]
},
"monitor": {
"config": {
"format": "",
"image_links": false,
"links": false,
"query": "new electric vehicle policies",
"recency_minutes": 1440,
"result_limit": 5,
"url": ""
},
"created_at": "2026-11-01 09:00:00",
"id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
"last_error": "",
"name": "Competitor pricing",
"schedule_cron": "CRON_TZ=America/New_York 0 9 * * *",
"status": "active",
"type": "search",
"updated_at": "2026-11-01 09:00:00",
"webhook_url": ""
}
}Delete a dataset
Delete a dataset and its rows. A dataset still being filled can't be deleted.
Inputs
- Dataset
dataset_idtextRequired - The dataset. Pick one, or give its id from an earlier step.
Outputs
dataset_idtext- The dataset deleted
deletedtrue/false- Always true once deleted
Example output
{
"dataset_id": "6f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
"deleted": true
}Delete a monitor
Delete a monitor and its schedule. Its past checks go with it.
Inputs
- Monitor
monitor_idtextRequired - The monitor. Pick one, or give its id from an earlier step.
Outputs
deletedtrue/false- Always true once deleted
monitor_idtext- The monitor deleted
Example output
{
"deleted": true,
"monitor_id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7"
}Get a dataset
Get a dataset: its columns, how many rows it has and whether it is still being filled.
Inputs
- Dataset
dataset_idtextRequired - The dataset. Pick one, or give its id from an earlier step.
Outputs
datasetobject- The dataset
is_finishedtrue/false- Whether it is no longer being filled
Example output
{
"dataset": {
"created_at": "2026-11-01T09:00:00Z",
"id": "6f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
"name": "Climbing gyms in Denver",
"row_count": 20,
"run": {
"error": "",
"finished_at": "2026-11-01T09:04:00Z",
"id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"started_at": "2026-11-01T09:00:01Z",
"status": "done"
},
"spec": {
"columns": [
{
"is_primary_key": true,
"name": "name",
"type": "string"
},
{
"is_primary_key": false,
"name": "website",
"type": "url"
}
],
"description": "Climbing gyms in Denver with their websites",
"name": "Climbing gyms in Denver"
},
"status": "ready",
"target_rows": 20
},
"is_finished": true
}Get a monitor
Get a monitor: what it watches, its schedule and whether it is running.
Inputs
- Monitor
monitor_idtextRequired - The monitor. Pick one, or give its id from an earlier step.
Outputs
monitorobject- The monitor
Example output
{
"monitor": {
"config": {
"format": "markdown",
"image_links": false,
"links": false,
"query": "",
"recency_minutes": 0,
"result_limit": 0,
"url": "https://example.com/pricing"
},
"created_at": "2026-11-01 09:00:00",
"id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
"last_error": "",
"name": "Competitor pricing",
"schedule_cron": "CRON_TZ=America/New_York 0 9 * * *",
"status": "active",
"type": "fetch",
"updated_at": "2026-11-01 09:00:00",
"webhook_url": ""
}
}Get a web agent run
Get an agent run: whether it has finished, its result or error, and each step it took.
Inputs
- Agent run
run_idtextRequired - The run. Pick a recent one, or give its id from an earlier step.
Outputs
is_finishedtrue/false- Whether it has completed, failed or been cancelled
resultobject- What the agent found, once it has
runobject- The run
Example output
{
"is_finished": true,
"result": {
"plan": "Pro",
"price": 29
},
"run": {
"created_at": "2026-11-01T10:30:00Z",
"error": {
"category": "",
"code": "",
"help_message": "",
"help_url": "",
"message": "",
"retry_after": 0
},
"finished_at": "2026-11-01T10:31:30Z",
"goal": "Get each plan's name and monthly price",
"num_of_steps": 5,
"profile_id": "",
"result": {
"plan": "Pro",
"price": 29
},
"run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"started_at": "2026-11-01T10:30:05Z",
"status": "COMPLETED",
"steps": [
{
"action": "Open the pricing page",
"duration": "1.2s",
"id": "evt_abc123",
"status": "COMPLETED",
"timestamp": "2026-11-01T10:30:05Z"
}
],
"streaming_url": "",
"url": "https://example.com/pricing",
"video_url": ""
}
}Get dataset rows
Get a dataset's rows in the order they were added, with its columns. Each row's values are under 'data', by column name.
Inputs
- Dataset
dataset_idtextRequired - The dataset. Pick one, or give its id from an earlier step.
- How many
limitnumber - How many rows to return, 1 to 2000. TinyFish's default is 500.From 1 to 2000.
- Next page cursor
cursortext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
columnslist- The columns
countnumber- How many came back on this page
has_moretrue/false- Whether there are more after this page
next_cursortext- Pass as 'Next page cursor' to get the next page; empty on the last
rowslist- The rows
Example output
{
"columns": [
{
"is_primary_key": true,
"label": "",
"name": "name",
"type": "string"
},
{
"is_primary_key": false,
"label": "",
"name": "website",
"type": "url"
}
],
"count": 1,
"has_more": false,
"next_cursor": "",
"rows": [
{
"data": {
"name": "Movement RiNo",
"website": "https://example.com"
},
"id": "1"
}
]
}Get research
Get a research run: whether it has finished, its report and the sources it cites.
Inputs
- Research run
research_run_idtextRequired - The research run. Pick a recent one, or give its id from an earlier step.
Outputs
citationslist- The sources the report cites
is_finishedtrue/false- Whether the research has stopped
reporttext- The report, or the quick answer while it is still running
research_runobject- The research run
Example output
{
"citations": [
"https://example.org/storage"
],
"is_finished": true,
"report": "Pumped hydro remains the cheapest long-duration storage.",
"research_run": {
"completed_at": "2026-11-01T12:05:00Z",
"created_at": "2026-11-01T12:00:00Z",
"deep_result": {
"citations": [
"https://example.org/storage"
],
"result": "Pumped hydro remains the cheapest long-duration storage.",
"termination_reason": "planner_done"
},
"error": {
"code": "",
"message": ""
},
"query": "Compare long-duration energy storage approaches",
"quick_result": {
"answer": "Pumped hydro leads on cost.",
"citations": [
"https://example.org/storage"
]
},
"quick_result_summary": "Pumped hydro leads on cost.",
"research_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"run_ids": [],
"status": "COMPLETED"
}
}Get wallet balance
Get how much money is left in the TinyFish wallet and how it reloads. Accounts still on a credits plan have no wallet.
Inputs
None.
Outputs
as_oftext- When the balance was read
auto_reloadtext- Whether it reloads by itself: on, off, unconfigured, paused_payment_failed or needs_payment_method
balancenumber- Money left; below zero when overdrawn
currencytext- The currency, USD
reload_belowtext- The balance that sets off a reload
reload_totext- The balance a reload tops up to
Example output
{
"as_of": "2026-11-01T18:04:11.220Z",
"auto_reload": "on",
"balance": 21.44,
"currency": "USD",
"reload_below": "5.00",
"reload_to": "25.00"
}List datasets
List the account's datasets, newest first.
Inputs
- How many
limitnumber - How many to return, 1 to 100. TinyFish's default is 20.From 1 to 100.
- Next page cursor
cursortext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
countnumber- How many came back on this page
datasetslist- The datasets
has_moretrue/false- Whether there are more after this page
next_cursortext- Pass as 'Next page cursor' to get the next page; empty on the last
Example output
{
"count": 1,
"datasets": [
{
"created_at": "2026-11-01T09:00:00Z",
"id": "6f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
"name": "Climbing gyms in Denver",
"row_count": 20,
"run": {
"error": "",
"finished_at": "2026-11-01T09:04:00Z",
"id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"started_at": "2026-11-01T09:00:01Z",
"status": "done"
},
"spec": {
"columns": [
{
"is_primary_key": true,
"name": "name",
"type": "string"
},
{
"is_primary_key": false,
"name": "website",
"type": "url"
}
],
"description": "Climbing gyms in Denver with their websites",
"name": "Climbing gyms in Denver"
},
"status": "ready",
"target_rows": 20
}
],
"has_more": false,
"next_cursor": ""
}List monitors
List every page and topic monitor on the account.
Inputs
None.
Outputs
countnumber- How many
monitorslist- The monitors
Example output
{
"count": 1,
"monitors": [
{
"config": {
"format": "markdown",
"image_links": false,
"links": false,
"query": "",
"recency_minutes": 0,
"result_limit": 0,
"url": "https://example.com/pricing"
},
"created_at": "2026-11-01 09:00:00",
"id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
"last_error": "",
"name": "Competitor pricing",
"schedule_cron": "CRON_TZ=America/New_York 0 9 * * *",
"status": "active",
"type": "fetch",
"updated_at": "2026-11-01 09:00:00",
"webhook_url": ""
}
]
}List research
List research runs, newest first, filtered by status, words or date.
Inputs
- Status
statustext - Only research with this status.One of:
QUEUED(Waiting to start),RUNNING,COMPLETED,FAILED,CANCELLED,TIMED_OUT(Timed out). - Question contains
question_containstext - Only research whose question contains these words.
- Created after
created_afterdate and time - Only those created after this time.
- Created before
created_beforedate and time - Only those created before this time.
- Order
ordertext - Sort by when they were created.One of:
desc(Newest first (default)),asc(Oldest first). - How many
limitnumber - How many to return, 1 to 100. TinyFish's default is 20.From 1 to 100.
- Next page cursor
cursortext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
countnumber- How many came back on this page
has_moretrue/false- Whether there are more after this page
next_cursortext- Pass as 'Next page cursor' to get the next page; empty on the last
research_runslist- The research runs
totalnumber- How many match, on every page
Example output
{
"count": 1,
"has_more": false,
"next_cursor": "",
"research_runs": [
{
"completed_at": "2026-11-01T12:05:00Z",
"created_at": "2026-11-01T12:00:00Z",
"deep_result": {
"citations": [
"https://example.org/storage"
],
"result": "Pumped hydro remains the cheapest long-duration storage.",
"termination_reason": "planner_done"
},
"error": {
"code": "",
"message": ""
},
"query": "Compare long-duration energy storage approaches",
"quick_result": {
"answer": "Pumped hydro leads on cost.",
"citations": [
"https://example.org/storage"
]
},
"quick_result_summary": "Pumped hydro leads on cost.",
"research_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"run_ids": [],
"status": "COMPLETED"
}
],
"total": 1
}List web agent runs
List agent runs, newest first, filtered by status, words in the goal or when they were created.
Inputs
- Status
statustext - Only runs with this status.One of:
PENDING(Waiting to start),RUNNING,COMPLETED,FAILED,CANCELLED. - Goal contains
goal_containstext - Only runs whose goal contains these words.
- Created after
created_afterdate and time - Only those created after this time.
- Created before
created_beforedate and time - Only those created before this time.
- Order
ordertext - Sort by when they were created.One of:
desc(Newest first (default)),asc(Oldest first). - How many
limitnumber - How many to return, 1 to 100. TinyFish's default is 20.From 1 to 100.
- Next page cursor
cursortext - The 'next_cursor' from an earlier page, to get the page after it.
Outputs
countnumber- How many came back on this page
has_moretrue/false- Whether there are more after this page
next_cursortext- Pass as 'Next page cursor' to get the next page; empty on the last
runslist- The runs
totalnumber- How many match, on every page
Example output
{
"count": 1,
"has_more": false,
"next_cursor": "",
"runs": [
{
"created_at": "2026-11-01T10:30:00Z",
"error": {
"category": "",
"code": "",
"help_message": "",
"help_url": "",
"message": "",
"retry_after": 0
},
"finished_at": "2026-11-01T10:31:30Z",
"goal": "Get each plan's name and monthly price",
"num_of_steps": 5,
"profile_id": "",
"result": {
"plan": "Pro",
"price": 29
},
"run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"started_at": "2026-11-01T10:30:05Z",
"status": "COMPLETED",
"steps": [],
"streaming_url": "",
"url": "https://example.com/pricing",
"video_url": ""
}
],
"total": 1
}Pause or resume a monitor
Pause a monitor's scheduled checks, or resume them. Running it twice is harmless.
Inputs
- Monitor
monitor_idtextRequired - The monitor. Pick one, or give its id from an earlier step.
- Set to
statetextRequired - Paused stops its checks; active resumes them.One of:
paused,active.
Outputs
monitorobject- The monitor
Example output
{
"monitor": {
"config": {
"format": "markdown",
"image_links": false,
"links": false,
"query": "",
"recency_minutes": 0,
"result_limit": 0,
"url": "https://example.com/pricing"
},
"created_at": "2026-11-01 09:00:00",
"id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
"last_error": "",
"name": "Competitor pricing",
"schedule_cron": "CRON_TZ=America/New_York 0 9 * * *",
"status": "paused",
"type": "fetch",
"updated_at": "2026-11-01 09:00:00",
"webhook_url": ""
}
}Read web pages
Read up to ten web pages and get each one's clean text, ready for an AI step, with its title and details. Pages that can't be read are listed with the reason. Free up to a daily allowance.
Inputs
- Pages
urlslistRequired - The web addresses to read, up to ten.
- Why
purposetext - What the text is for, which helps TinyFish read the right parts.
- Text as
page_formattext - How each page's text comes back.One of:
markdown(Markdown (default)),html(Cleaned HTML),json(Structured document). - Include links
include_linkstrue/false - Also list every link on the page.
- Include image links
include_image_linkstrue/false - Also list the address of every image on the page.
- Include page details
include_page_detailstrue/false - Also return what the page says about itself: its preview image, keywords and social sharing text.
- Only these parts
only_partslist - Read only the parts of the page matching these CSS selectors, such as article or main.
- Skip these parts
skip_partslist - Leave out the parts matching these CSS selectors, such as .comments.
- Always read a fresh copy
fresh_copytrue/false - Turn on to skip any copy TinyFish read recently.
Outputs
countnumber- How many pages were read
error_countnumber- How many could not be read
errorslist- The pages that could not be read, with the reason
pageslist- The pages that were read
Example output
{
"count": 1,
"error_count": 0,
"errors": [],
"pages": [
{
"author": "",
"description": "",
"final_url": "https://example.com/pricing",
"format": "markdown",
"image_links": [],
"language": "en",
"links": [],
"page_metadata": {},
"published_date": "",
"text": "# Pricing\nPro: $29/month",
"title": "Pricing",
"url": "https://example.com/pricing"
}
]
}Run a web agent
Send an AI agent to a website to do what the goal says, such as find information, fill in a form or collect a list, and wait for its result (up to 10 minutes). Each run is billed to your TinyFish wallet. For longer jobs, use 'Start a web agent run'.
Inputs
- Website
urltextRequired - The page the agent starts on.
- Goal
goaltextRequired - What the agent should do there, in plain words, such as "Find the pricing page and get each plan's name and monthly price".
- Result fields
result_fieldsobject - The fields the result must have, each with a type: text, number, true/false, date, link or list. For example {"plan": "text", "price": "number"}. Leave empty to let the agent choose.
- Return a list
result_is_listtrue/false - Turn on to get a list of items with the result fields (under 'items') rather than one.
- Browser
browsertext - Use the stealth browser for sites that block automated visitors.One of:
lite(Standard (default)),stealth(Stealth, for sites that block bots). - Browse from
proxy_countrytext - Browse through a connection in this country, for sites that show different content by location.One of:
US(United States),GB(United Kingdom),CA(Canada),DE(Germany),FR(France),JP(Japan),AU(Australia). - Most steps
max_stepsnumber - Stop after this many steps, 1 to 500, to keep the cost down. TinyFish's default is 150.From 1 to 500.
- Time limit (minutes)
time_limit_minutesnumber - Stop after this many minutes. No limit by default.At least 1.
- Saved sign-in
profile_idtext - A browser profile saved in TinyFish with your sign-ins, so the agent starts signed in.
- Use saved passwords
use_saved_passwordstrue/false - Let the agent sign in with passwords from the password manager connected to TinyFish.
Outputs
resultobject- What the agent found, in the run's result fields
runobject- The run: its status, result, error and steps
Example output
{
"result": {
"plan": "Pro",
"price": 29
},
"run": {
"created_at": "2026-11-01T10:30:00Z",
"error": {
"category": "",
"code": "",
"help_message": "",
"help_url": "",
"message": "",
"retry_after": 0
},
"finished_at": "2026-11-01T10:31:30Z",
"goal": "Get each plan's name and monthly price",
"num_of_steps": 5,
"profile_id": "",
"result": {
"plan": "Pro",
"price": 29
},
"run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"started_at": "2026-11-01T10:30:05Z",
"status": "COMPLETED",
"steps": [
{
"action": "Open the pricing page",
"duration": "1.2s",
"id": "evt_abc123",
"status": "COMPLETED",
"timestamp": "2026-11-01T10:30:05Z"
}
],
"streaming_url": "",
"url": "https://example.com/pricing",
"video_url": ""
}
}Search the web
Search the web, news or research papers and get the ranked results with titles, snippets and links. Free up to a daily allowance.
Inputs
- Search for
querytextRequired - What to search for.
- Why
purposetext - What the results are for, which helps rank them.
- Search in
search_intext - Web pages, news articles or research papers.One of:
web(Web pages (default)),news(News articles),research_paper(Research papers). - Country
countrytext - Results for this country, as a two-letter code such as US or FR.
- Language
languagetext - Results in this language, as a code such as en or fr.
- Only these sites
only_siteslist - Only results from these websites, such as github.com.
- Not these sites
exclude_siteslist - Leave out results from these websites.
- Published on or after
published_afterdate - Only results from this date on.
- Published on or before
published_beforedate - Only results up to this date.
- Page
pagenumber - Which page of results, from 0 (the first) to 10.From 0 to 10.
Outputs
countnumber- How many results came back
pagenumber- The page of results, from 0
querytext- The search that was run
resultslist- The results, best first
Example output
{
"count": 1,
"page": 0,
"query": "web automation tools",
"results": [
{
"authors": [],
"cited_by_count": 0,
"date": "",
"pdf_url": "",
"position": 1,
"publisher": "",
"site_name": "example.com",
"snippet": "A round-up of web automation tools...",
"title": "Top web automation tools",
"url": "https://example.com/tools",
"venue": "",
"year": 0
}
]
}Start a web agent run
Start an AI agent on a website in the background and continue at once. Follow it with 'Get a web agent run', or use the 'Agent run finishes' trigger. Each run is billed to your TinyFish wallet.
Inputs
- Website
urltextRequired - The page the agent starts on.
- Goal
goaltextRequired - What the agent should do there, in plain words, such as "Find the pricing page and get each plan's name and monthly price".
- Result fields
result_fieldsobject - The fields the result must have, each with a type: text, number, true/false, date, link or list. For example {"plan": "text", "price": "number"}. Leave empty to let the agent choose.
- Return a list
result_is_listtrue/false - Turn on to get a list of items with the result fields (under 'items') rather than one.
- Browser
browsertext - Use the stealth browser for sites that block automated visitors.One of:
lite(Standard (default)),stealth(Stealth, for sites that block bots). - Browse from
proxy_countrytext - Browse through a connection in this country, for sites that show different content by location.One of:
US(United States),GB(United Kingdom),CA(Canada),DE(Germany),FR(France),JP(Japan),AU(Australia). - Most steps
max_stepsnumber - Stop after this many steps, 1 to 500, to keep the cost down. TinyFish's default is 150.From 1 to 500.
- Time limit (minutes)
time_limit_minutesnumber - Stop after this many minutes. No limit by default.At least 1.
- Saved sign-in
profile_idtext - A browser profile saved in TinyFish with your sign-ins, so the agent starts signed in.
- Use saved passwords
use_saved_passwordstrue/false - Let the agent sign in with passwords from the password manager connected to TinyFish.
Outputs
goaltext- The goal it was given
run_idtext- The new run's id
statustext- PENDING: it has not started yet
Example output
{
"goal": "Get each plan's name and monthly price",
"run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "PENDING"
}Start research
Have TinyFish research a question across many sources and write a report with citations, in the background. Follow it with 'Get research', or use the 'Research finishes' trigger. Two a day are free; after that each is billed to your wallet.
Inputs
- Question
questiontextRequired - What to research, in plain words.
- Depth
depthtext - How thorough to be. Max takes longer and costs more.One of:
deep(Deep (default)),max(Max, the most thorough). - Report language
report_languagetext - Write the report in this language, as a code such as en or ja.
- Search in
search_intext - Web pages, news articles or research papers.One of:
web(Web pages (default)),news(News articles),research_paper(Research papers). - Published on or after
published_afterdate - Only results from this date on.
- Published on or before
published_beforedate - Only results up to this date.
- Prefer these sites
focus_siteslist - Websites to lean on, such as who.int.
- Only use those sites
only_focus_sitestrue/false - Turn on to use nothing but the preferred sites.
- Never use these sites
blocked_siteslist - Websites to leave out.
Outputs
questiontext- The question it was given
research_run_idtext- The new research run's id
statustext- QUEUED: it has not started yet
Example output
{
"question": "Compare long-duration energy storage approaches",
"research_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "QUEUED"
}Update a monitor
Rename a monitor, change what matters to it, or change its schedule. Fields left empty keep their values. What it watches can't be changed: create a new monitor for that.
Inputs
- Monitor
monitor_idtextRequired - The monitor. Pick one, or give its id from an earlier step.
- How often
frequencytext - How often TinyFish checks. Leave empty to keep the current schedule.One of:
hourly(Every hour),every_6_hours(Every 6 hours),daily(Every day),weekdays(Every weekday),weekly(Every week). - At
at_timetime - The time of day it checks, 9:00 by default. For every hour, only the minutes count.
- On
weekdaytext - The day of the week, for a weekly check.One of:
1(Monday (default)),2(Tuesday),3(Wednesday),4(Thursday),5(Friday),6(Saturday),0(Sunday). - Time zone
time_zonetext - The time zone of that time. UTC by default.
- Name
nametext - A name to know the monitor by, up to 100 characters.
- What matters
purposetext - The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.
Outputs
monitorobject- The monitor
Example output
{
"monitor": {
"config": {
"format": "markdown",
"image_links": false,
"links": false,
"query": "",
"recency_minutes": 0,
"result_limit": 0,
"url": "https://example.com/pricing"
},
"created_at": "2026-11-01 09:00:00",
"id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
"last_error": "",
"name": "Competitor pricing",
"schedule_cron": "CRON_TZ=America/New_York 0 9 * * *",
"status": "active",
"type": "fetch",
"updated_at": "2026-11-01 09:00:00",
"webhook_url": ""
}
}