# TinyFish

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

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/tinyfish

## Actions

### 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_id`, text, required): The run. Pick a recent one, or give its id from an earlier step.

**Outputs**

- `cancelled` (true/false): Whether it is now cancelled
- `cancelled_at` (text): When it was cancelled, if it was
- `message` (text): TinyFish's note, such as 'Run already finished'
- `run_id` (text): The run
- `status` (text): Its status now: CANCELLED, COMPLETED or FAILED

**Example output**

```json
{
  "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_id`, text, required): The research run. Pick a recent one, or give its id from an earlier step.

**Outputs**

- `cancelled` (true/false): Whether this cancelled it
- `research_run_id` (text): The research run
- `status` (text): Its status now

**Example output**

```json
{
  "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_id`, text, required): The monitor. Pick one, or give its id from an earlier step.

**Outputs**

- `check` (object): The check
- `count` (number): How many results
- `monitor_id` (text): The monitor
- `results` (list): What it found: the page, or the search's results

**Example output**

```json
{
  "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 (`description`, text, required): What the dataset should contain, in plain words.
- Rows (`target_rows`, number): How many rows to fill it to, 1 to 250. From 1 to 250.
- Start filling now (`fill_now`, true/false): On by default. Turn off to only plan its columns.

**Outputs**

- `dataset` (object): The dataset

**Example output**

```json
{
  "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 (`url`, text, required): The web address of the page to watch.
- How often (`frequency`, text, required): 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_time`, time): The time of day it checks, 9:00 by default. For every hour, only the minutes count.
- On (`weekday`, text): 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_zone`, text): The time zone of that time. UTC by default.
- Name (`name`, text): A name to know the monitor by, up to 100 characters.
- What matters (`purpose`, text): The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.
- Text as (`page_format`, text): How each page's text comes back. One of: `markdown` (Markdown (default)), `html` (Cleaned HTML), `json` (Structured document).
- Include links (`include_links`, true/false): Also list every link on the page.
- Include image links (`include_image_links`, true/false): Also list the address of every image on the page.

**Outputs**

- `baseline` (object): Its first check, kept to compare with
- `monitor` (object): The new monitor

**Example output**

```json
{
  "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 (`query`, text, required): The search to repeat.
- How often (`frequency`, text, required): 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_time`, time): The time of day it checks, 9:00 by default. For every hour, only the minutes count.
- On (`weekday`, text): 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_zone`, text): The time zone of that time. UTC by default.
- Name (`name`, text): A name to know the monitor by, up to 100 characters.
- What matters (`purpose`, text): The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.
- Published within (`published_within`, text): 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_limit`, number): How many results to compare each time, 1 to 10. TinyFish's default is 10. From 1 to 10.

**Outputs**

- `baseline` (object): Its first check, kept to compare with
- `monitor` (object): The new monitor

**Example output**

```json
{
  "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_id`, text, required): The dataset. Pick one, or give its id from an earlier step.

**Outputs**

- `dataset_id` (text): The dataset deleted
- `deleted` (true/false): Always true once deleted

**Example output**

```json
{
  "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_id`, text, required): The monitor. Pick one, or give its id from an earlier step.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `monitor_id` (text): The monitor deleted

**Example output**

```json
{
  "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_id`, text, required): The dataset. Pick one, or give its id from an earlier step.

**Outputs**

- `dataset` (object): The dataset
- `is_finished` (true/false): Whether it is no longer being filled

**Example output**

```json
{
  "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_id`, text, required): The monitor. Pick one, or give its id from an earlier step.

**Outputs**

- `monitor` (object): The monitor

**Example output**

```json
{
  "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_id`, text, required): The run. Pick a recent one, or give its id from an earlier step.

**Outputs**

- `is_finished` (true/false): Whether it has completed, failed or been cancelled
- `result` (object): What the agent found, once it has
- `run` (object): The run

**Example output**

```json
{
  "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_id`, text, required): The dataset. Pick one, or give its id from an earlier step.
- How many (`limit`, number): How many rows to return, 1 to 2000. TinyFish's default is 500. From 1 to 2000.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `columns` (list): The columns
- `count` (number): How many came back on this page
- `has_more` (true/false): Whether there are more after this page
- `next_cursor` (text): Pass as 'Next page cursor' to get the next page; empty on the last
- `rows` (list): The rows

**Example output**

```json
{
  "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_id`, text, required): The research run. Pick a recent one, or give its id from an earlier step.

**Outputs**

- `citations` (list): The sources the report cites
- `is_finished` (true/false): Whether the research has stopped
- `report` (text): The report, or the quick answer while it is still running
- `research_run` (object): The research run

**Example output**

```json
{
  "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_of` (text): When the balance was read
- `auto_reload` (text): Whether it reloads by itself: on, off, unconfigured, paused_payment_failed or needs_payment_method
- `balance` (number): Money left; below zero when overdrawn
- `currency` (text): The currency, USD
- `reload_below` (text): The balance that sets off a reload
- `reload_to` (text): The balance a reload tops up to

**Example output**

```json
{
  "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 (`limit`, number): How many to return, 1 to 100. TinyFish's default is 20. From 1 to 100.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many came back on this page
- `datasets` (list): The datasets
- `has_more` (true/false): Whether there are more after this page
- `next_cursor` (text): Pass as 'Next page cursor' to get the next page; empty on the last

**Example output**

```json
{
  "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**

- `count` (number): How many
- `monitors` (list): The monitors

**Example output**

```json
{
  "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 (`status`, text): Only research with this status. One of: `QUEUED` (Waiting to start), `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, `TIMED_OUT` (Timed out).
- Question contains (`question_contains`, text): Only research whose question contains these words.
- Created after (`created_after`, date and time): Only those created after this time.
- Created before (`created_before`, date and time): Only those created before this time.
- Order (`order`, text): Sort by when they were created. One of: `desc` (Newest first (default)), `asc` (Oldest first).
- How many (`limit`, number): How many to return, 1 to 100. TinyFish's default is 20. From 1 to 100.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many came back on this page
- `has_more` (true/false): Whether there are more after this page
- `next_cursor` (text): Pass as 'Next page cursor' to get the next page; empty on the last
- `research_runs` (list): The research runs
- `total` (number): How many match, on every page

**Example output**

```json
{
  "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 (`status`, text): Only runs with this status. One of: `PENDING` (Waiting to start), `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`.
- Goal contains (`goal_contains`, text): Only runs whose goal contains these words.
- Created after (`created_after`, date and time): Only those created after this time.
- Created before (`created_before`, date and time): Only those created before this time.
- Order (`order`, text): Sort by when they were created. One of: `desc` (Newest first (default)), `asc` (Oldest first).
- How many (`limit`, number): How many to return, 1 to 100. TinyFish's default is 20. From 1 to 100.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many came back on this page
- `has_more` (true/false): Whether there are more after this page
- `next_cursor` (text): Pass as 'Next page cursor' to get the next page; empty on the last
- `runs` (list): The runs
- `total` (number): How many match, on every page

**Example output**

```json
{
  "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_id`, text, required): The monitor. Pick one, or give its id from an earlier step.
- Set to (`state`, text, required): Paused stops its checks; active resumes them. One of: `paused`, `active`.

**Outputs**

- `monitor` (object): The monitor

**Example output**

```json
{
  "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 (`urls`, list, required): The web addresses to read, up to ten.
- Why (`purpose`, text): What the text is for, which helps TinyFish read the right parts.
- Text as (`page_format`, text): How each page's text comes back. One of: `markdown` (Markdown (default)), `html` (Cleaned HTML), `json` (Structured document).
- Include links (`include_links`, true/false): Also list every link on the page.
- Include image links (`include_image_links`, true/false): Also list the address of every image on the page.
- Include page details (`include_page_details`, true/false): Also return what the page says about itself: its preview image, keywords and social sharing text.
- Only these parts (`only_parts`, list): Read only the parts of the page matching these CSS selectors, such as article or main.
- Skip these parts (`skip_parts`, list): Leave out the parts matching these CSS selectors, such as .comments.
- Always read a fresh copy (`fresh_copy`, true/false): Turn on to skip any copy TinyFish read recently.

**Outputs**

- `count` (number): How many pages were read
- `error_count` (number): How many could not be read
- `errors` (list): The pages that could not be read, with the reason
- `pages` (list): The pages that were read

**Example output**

```json
{
  "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 (`url`, text, required): The page the agent starts on.
- Goal (`goal`, text, required): 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_fields`, object): 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_list`, true/false): Turn on to get a list of items with the result fields (under 'items') rather than one.
- Browser (`browser`, text): 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_country`, text): 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_steps`, number): 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_minutes`, number): Stop after this many minutes. No limit by default. At least 1.
- Saved sign-in (`profile_id`, text): A browser profile saved in TinyFish with your sign-ins, so the agent starts signed in.
- Use saved passwords (`use_saved_passwords`, true/false): Let the agent sign in with passwords from the password manager connected to TinyFish.

**Outputs**

- `result` (object): What the agent found, in the run's result fields
- `run` (object): The run: its status, result, error and steps

**Example output**

```json
{
  "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 (`query`, text, required): What to search for.
- Why (`purpose`, text): What the results are for, which helps rank them.
- Search in (`search_in`, text): Web pages, news articles or research papers. One of: `web` (Web pages (default)), `news` (News articles), `research_paper` (Research papers).
- Country (`country`, text): Results for this country, as a two-letter code such as US or FR.
- Language (`language`, text): Results in this language, as a code such as en or fr.
- Only these sites (`only_sites`, list): Only results from these websites, such as github.com.
- Not these sites (`exclude_sites`, list): Leave out results from these websites.
- Published on or after (`published_after`, date): Only results from this date on.
- Published on or before (`published_before`, date): Only results up to this date.
- Page (`page`, number): Which page of results, from 0 (the first) to 10. From 0 to 10.

**Outputs**

- `count` (number): How many results came back
- `page` (number): The page of results, from 0
- `query` (text): The search that was run
- `results` (list): The results, best first

**Example output**

```json
{
  "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 (`url`, text, required): The page the agent starts on.
- Goal (`goal`, text, required): 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_fields`, object): 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_list`, true/false): Turn on to get a list of items with the result fields (under 'items') rather than one.
- Browser (`browser`, text): 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_country`, text): 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_steps`, number): 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_minutes`, number): Stop after this many minutes. No limit by default. At least 1.
- Saved sign-in (`profile_id`, text): A browser profile saved in TinyFish with your sign-ins, so the agent starts signed in.
- Use saved passwords (`use_saved_passwords`, true/false): Let the agent sign in with passwords from the password manager connected to TinyFish.

**Outputs**

- `goal` (text): The goal it was given
- `run_id` (text): The new run's id
- `status` (text): PENDING: it has not started yet

**Example output**

```json
{
  "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 (`question`, text, required): What to research, in plain words.
- Depth (`depth`, text): How thorough to be. Max takes longer and costs more. One of: `deep` (Deep (default)), `max` (Max, the most thorough).
- Report language (`report_language`, text): Write the report in this language, as a code such as en or ja.
- Search in (`search_in`, text): 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_after`, date): Only results from this date on.
- Published on or before (`published_before`, date): Only results up to this date.
- Prefer these sites (`focus_sites`, list): Websites to lean on, such as who.int.
- Only use those sites (`only_focus_sites`, true/false): Turn on to use nothing but the preferred sites.
- Never use these sites (`blocked_sites`, list): Websites to leave out.

**Outputs**

- `question` (text): The question it was given
- `research_run_id` (text): The new research run's id
- `status` (text): QUEUED: it has not started yet

**Example output**

```json
{
  "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_id`, text, required): The monitor. Pick one, or give its id from an earlier step.
- How often (`frequency`, text): 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_time`, time): The time of day it checks, 9:00 by default. For every hour, only the minutes count.
- On (`weekday`, text): 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_zone`, text): The time zone of that time. UTC by default.
- Name (`name`, text): A name to know the monitor by, up to 100 characters.
- What matters (`purpose`, text): The change you care about, such as "the Pro plan's price changes". TinyFish judges each change against it.

**Outputs**

- `monitor` (object): The monitor

**Example output**

```json
{
  "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": ""
  }
}
```
