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

ActionWhat it does
Cancel a web agent runStop an agent run started with 'Start a web agent run'.
Cancel researchStop a research run that is still working.
Check a monitor nowCheck a monitor's page or search now, outside its schedule, and get what it found.
Create a datasetDescribe 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 monitorHave TinyFish read a page on a schedule and note what changed.
Create a topic monitorHave TinyFish repeat a web search on a schedule and note new results.
Delete a datasetDelete a dataset and its rows.
Delete a monitorDelete a monitor and its schedule.
Get a datasetGet a dataset: its columns, how many rows it has and whether it is still being filled.
Get a monitorGet a monitor: what it watches, its schedule and whether it is running.
Get a web agent runGet an agent run: whether it has finished, its result or error, and each step it took.
Get dataset rowsGet a dataset's rows in the order they were added, with its columns.
Get researchGet a research run: whether it has finished, its report and the sources it cites.
Get wallet balanceGet how much money is left in the TinyFish wallet and how it reloads.
List datasetsList the account's datasets, newest first.
List monitorsList every page and topic monitor on the account.
List researchList research runs, newest first, filtered by status, words or date.
List web agent runsList agent runs, newest first, filtered by status, words in the goal or when they were created.
Pause or resume a monitorPause a monitor's scheduled checks, or resume them.
Read web pagesRead 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 agentSend 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 webSearch the web, news or research papers and get the ranked results with titles, snippets and links.
Start a web agent runStart an AI agent on a website in the background and continue at once.
Start researchHave TinyFish research a question across many sources and write a report with citations, in the background.
Update a monitorRename 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 runrun_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 runresearch_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

Monitormonitor_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 holdsdescriptiontextRequired
What the dataset should contain, in plain words.
Rowstarget_rowsnumber
How many rows to fill it to, 1 to 250.From 1 to 250.
Start filling nowfill_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

PageurltextRequired
The web address of the page to watch.
How oftenfrequencytextRequired
How often TinyFish checks.One of: hourly (Every hour), every_6_hours (Every 6 hours), daily (Every day), weekdays (Every weekday), weekly (Every week).
Atat_timetime
The time of day it checks, 9:00 by default. For every hour, only the minutes count.
Onweekdaytext
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 zonetime_zonetext
The time zone of that time. UTC by default.
Namenametext
A name to know the monitor by, up to 100 characters.
What matterspurposetext
The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.
Text aspage_formattext
How each page's text comes back.One of: markdown (Markdown (default)), html (Cleaned HTML), json (Structured document).
Include linksinclude_linkstrue/false
Also list every link on the page.
Include image linksinclude_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 forquerytextRequired
The search to repeat.
How oftenfrequencytextRequired
How often TinyFish checks.One of: hourly (Every hour), every_6_hours (Every 6 hours), daily (Every day), weekdays (Every weekday), weekly (Every week).
Atat_timetime
The time of day it checks, 9:00 by default. For every hour, only the minutes count.
Onweekdaytext
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 zonetime_zonetext
The time zone of that time. UTC by default.
Namenametext
A name to know the monitor by, up to 100 characters.
What matterspurposetext
The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.
Published withinpublished_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 compareresult_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

Datasetdataset_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

Monitormonitor_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

Datasetdataset_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

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

Datasetdataset_idtextRequired
The dataset. Pick one, or give its id from an earlier step.
How manylimitnumber
How many rows to return, 1 to 2000. TinyFish's default is 500.From 1 to 2000.
Next page cursorcursortext
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 runresearch_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 manylimitnumber
How many to return, 1 to 100. TinyFish's default is 20.From 1 to 100.
Next page cursorcursortext
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

Statusstatustext
Only research with this status.One of: QUEUED (Waiting to start), RUNNING, COMPLETED, FAILED, CANCELLED, TIMED_OUT (Timed out).
Question containsquestion_containstext
Only research whose question contains these words.
Created aftercreated_afterdate and time
Only those created after this time.
Created beforecreated_beforedate and time
Only those created before this time.
Orderordertext
Sort by when they were created.One of: desc (Newest first (default)), asc (Oldest first).
How manylimitnumber
How many to return, 1 to 100. TinyFish's default is 20.From 1 to 100.
Next page cursorcursortext
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

Statusstatustext
Only runs with this status.One of: PENDING (Waiting to start), RUNNING, COMPLETED, FAILED, CANCELLED.
Goal containsgoal_containstext
Only runs whose goal contains these words.
Created aftercreated_afterdate and time
Only those created after this time.
Created beforecreated_beforedate and time
Only those created before this time.
Orderordertext
Sort by when they were created.One of: desc (Newest first (default)), asc (Oldest first).
How manylimitnumber
How many to return, 1 to 100. TinyFish's default is 20.From 1 to 100.
Next page cursorcursortext
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

Monitormonitor_idtextRequired
The monitor. Pick one, or give its id from an earlier step.
Set tostatetextRequired
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

PagesurlslistRequired
The web addresses to read, up to ten.
Whypurposetext
What the text is for, which helps TinyFish read the right parts.
Text aspage_formattext
How each page's text comes back.One of: markdown (Markdown (default)), html (Cleaned HTML), json (Structured document).
Include linksinclude_linkstrue/false
Also list every link on the page.
Include image linksinclude_image_linkstrue/false
Also list the address of every image on the page.
Include page detailsinclude_page_detailstrue/false
Also return what the page says about itself: its preview image, keywords and social sharing text.
Only these partsonly_partslist
Read only the parts of the page matching these CSS selectors, such as article or main.
Skip these partsskip_partslist
Leave out the parts matching these CSS selectors, such as .comments.
Always read a fresh copyfresh_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

WebsiteurltextRequired
The page the agent starts on.
GoalgoaltextRequired
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 fieldsresult_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 listresult_is_listtrue/false
Turn on to get a list of items with the result fields (under 'items') rather than one.
Browserbrowsertext
Use the stealth browser for sites that block automated visitors.One of: lite (Standard (default)), stealth (Stealth, for sites that block bots).
Browse fromproxy_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 stepsmax_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-inprofile_idtext
A browser profile saved in TinyFish with your sign-ins, so the agent starts signed in.
Use saved passwordsuse_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 forquerytextRequired
What to search for.
Whypurposetext
What the results are for, which helps rank them.
Search insearch_intext
Web pages, news articles or research papers.One of: web (Web pages (default)), news (News articles), research_paper (Research papers).
Countrycountrytext
Results for this country, as a two-letter code such as US or FR.
Languagelanguagetext
Results in this language, as a code such as en or fr.
Only these sitesonly_siteslist
Only results from these websites, such as github.com.
Not these sitesexclude_siteslist
Leave out results from these websites.
Published on or afterpublished_afterdate
Only results from this date on.
Published on or beforepublished_beforedate
Only results up to this date.
Pagepagenumber
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

WebsiteurltextRequired
The page the agent starts on.
GoalgoaltextRequired
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 fieldsresult_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 listresult_is_listtrue/false
Turn on to get a list of items with the result fields (under 'items') rather than one.
Browserbrowsertext
Use the stealth browser for sites that block automated visitors.One of: lite (Standard (default)), stealth (Stealth, for sites that block bots).
Browse fromproxy_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 stepsmax_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-inprofile_idtext
A browser profile saved in TinyFish with your sign-ins, so the agent starts signed in.
Use saved passwordsuse_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

QuestionquestiontextRequired
What to research, in plain words.
Depthdepthtext
How thorough to be. Max takes longer and costs more.One of: deep (Deep (default)), max (Max, the most thorough).
Report languagereport_languagetext
Write the report in this language, as a code such as en or ja.
Search insearch_intext
Web pages, news articles or research papers.One of: web (Web pages (default)), news (News articles), research_paper (Research papers).
Published on or afterpublished_afterdate
Only results from this date on.
Published on or beforepublished_beforedate
Only results up to this date.
Prefer these sitesfocus_siteslist
Websites to lean on, such as who.int.
Only use those sitesonly_focus_sitestrue/false
Turn on to use nothing but the preferred sites.
Never use these sitesblocked_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

Monitormonitor_idtextRequired
The monitor. Pick one, or give its id from an earlier step.
How oftenfrequencytext
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).
Atat_timetime
The time of day it checks, 9:00 by default. For every hour, only the minutes count.
Onweekdaytext
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 zonetime_zonetext
The time zone of that time. UTC by default.
Namenametext
A name to know the monitor by, up to 100 characters.
What matterspurposetext
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": ""
  }
}

On this page