> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TinyMonitor API Reference

> Create and manage Page and Topic Monitors through the REST API

## Base URL

```text theme={null}
https://agent.tinyfish.ai
```

All requests require an `X-API-Key` header. See [Authentication](https://docs.tinyfish.ai/authentication.md).

## Endpoints

| Method | Path | Description |
| - | - | - |
| `POST` | `/v1/monitors` | Create a Monitor and capture its baseline |
| `GET` | `/v1/monitors` | List your Monitors |
| `GET` | `/v1/monitors/{id}` | Get one Monitor |
| `PATCH` | `/v1/monitors/{id}` | Pause, resume, or edit a Monitor |
| `DELETE` | `/v1/monitors/{id}` | Delete a Monitor and its schedule |
| `POST` | `/v1/monitors/{id}/runs` | Run a Monitor immediately |

## Create a Monitor

> [tab] Page
>
> ```bash cURL theme={null}
> curl -X POST "https://agent.tinyfish.ai/v1/monitors" \
>   -H "X-API-Key: $TINYFISH_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "fetch",
>     "name": "Competitor pricing",
>     "config": {
>       "url": "https://example.com/pricing",
>       "format": "markdown"
>     },
>     "schedule_cron": "0 9 * * *",
>     "purpose": "A plan price changes",
>     "webhook_url": "https://example.com/webhooks/monitor"
>   }'
> ```
>
> ```python Python theme={null}
> from tinyfish import TinyFish
>
> client = TinyFish()
> created = client.monitors.create(
>     "fetch",
>     {"url": "https://example.com/pricing", "format": "markdown"},
>     "0 9 * * *",
>     name="Competitor pricing",
>     purpose="A plan price changes",
>     webhook_url="https://example.com/webhooks/monitor",
> )
> print(created.monitor.id)
> ```
>
> ```typescript TypeScript theme={null}
> import { TinyFish } from "@tiny-fish/sdk";
>
> const client = new TinyFish();
> const { monitor, run } = await client.monitors.create({
>   type: "fetch",
>   name: "Competitor pricing",
>   config: { url: "https://example.com/pricing", format: "markdown" },
>   schedule_cron: "0 9 * * *",
>   purpose: "A plan price changes",
>   webhook_url: "https://example.com/webhooks/monitor",
> });
> ```

> [tab] Topic
>
> ```bash cURL theme={null}
> curl -X POST "https://agent.tinyfish.ai/v1/monitors" \
>   -H "X-API-Key: $TINYFISH_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "search",
>     "name": "EV policy updates",
>     "config": {
>       "query": "new electric vehicle policies",
>       "recency_minutes": 1440,
>       "result_limit": 5
>     },
>     "schedule_cron": "0 */6 * * *",
>     "purpose": "A new policy is announced"
>   }'
> ```
>
> ```python Python theme={null}
> from tinyfish import TinyFish
>
> client = TinyFish()
> created = client.monitors.create(
>     "search",
>     {"query": "new electric vehicle policies", "recency_minutes": 1440, "result_limit": 5},
>     "0 */6 * * *",
>     name="EV policy updates",
>     purpose="A new policy is announced",
> )
> print(created.monitor.id)
> ```
>
> ```typescript TypeScript theme={null}
> import { TinyFish } from "@tiny-fish/sdk";
>
> const client = new TinyFish();
> const { monitor, run } = await client.monitors.create({
>   type: "search",
>   name: "EV policy updates",
>   config: {
>     query: "new electric vehicle policies",
>     recency_minutes: 1440,
>     result_limit: 5,
>   },
>   schedule_cron: "0 */6 * * *",
>   purpose: "A new policy is announced",
> });
> ```

The response is `201 Created` and contains the new Monitor plus its first baseline run:

```json theme={null}
{
  "monitor": {
    "id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
    "name": "Competitor pricing",
    "type": "fetch",
    "config": {
      "url": "https://example.com/pricing",
      "format": "markdown",
      "links": false,
      "image_links": false,
      "ttl": 0
    },
    "schedule_cron": "0 9 * * *",
    "status": "active",
    "last_error": null,
    "webhook_url": "https://example.com/webhooks/monitor",
    "created_at": "2026-09-09 09:00:00",
    "updated_at": "2026-09-09 09:00:00"
  },
  "run": {
    "id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
    "is_baseline": true,
    "results": [
      {
        "url": "https://example.com/pricing",
        "final_url": "https://example.com/pricing",
        "title": "Pricing",
        "description": null,
        "language": "en",
        "format": "markdown",
        "text": "# Pricing",
        "author": null,
        "published_date": null,
        "latency_ms": 412
      }
    ],
    "errors": []
  }
}
```

Monitor responses do not currently echo `purpose` or dashboard-managed email settings.

### Common Fields

**type** `string` *required*

`fetch` for a Page Monitor or `search` for a Topic Monitor.

**config** `object` *required*

Type-specific configuration. See the Page and Topic fields below.

**schedule\_cron** `string` *required*

A five-field cron expression. It runs in UTC unless prefixed with an IANA time zone, for example
`CRON_TZ=America/New_York 0 9 * * 1-5`. Topic schedules must keep every run at least 30 minutes
apart.

**name** `string`

Optional Monitor name, up to 100 characters.

**purpose** `string`

Optional description of the change that matters, up to 2000 characters. TinyFish evaluates
detected changes against this purpose.

**webhook\_url** `string`

Optional public HTTP or HTTPS URL that receives every scheduled run result.

> [!NOTE]
>
> Email delivery is currently configured in the dashboard. The REST API does not accept email
> settings.

### Page Config

**config.url** `string` *required*

Public HTTP or HTTPS webpage URL.

**config.format** `string` (default: json)

Extracted content format: `json`, `markdown`, or `html`.

**config.links** `boolean` (default: false)

Include links found on the webpage.

**config.image\_links** `boolean` (default: false)

Include image links found on the webpage.

**config.include\_selectors** `string[]`

CSS selectors (1-20) that scope each run to matching elements, so the Monitor only reports
changes inside them, for example `[".price"]`. Works like Fetch's
[`include_selectors`](https://docs.tinyfish.ai/tinyfetch/reference). If no selector matches when you create the
Monitor, the request fails with `422`, lists selectors found on the page, and no Monitor is
created. If a later run
matches nothing, that run fails with `selector_not_matched`.

**config.exclude\_selectors** `string[]`

CSS selectors (1-20) for elements to remove before comparing, such as ads, timestamps, or
rotating banners.

Page Monitors always run Fetch with `ttl: 0` to prefer fresh content. The deprecated `config.ttl`
field is accepted for compatibility but does not change this behavior.

### Topic Config

**config.query** `string` *required*

Search query to repeat, up to 2000 characters.

**config.recency\_minutes** `integer`

Optional freshness window from 1 to 5,256,000 minutes.

**config.result\_limit** `integer` (default: 10)

Number of results to compare per run, from 1 to 10.

## List and Get Monitors

```bash cURL theme={null}
curl "https://agent.tinyfish.ai/v1/monitors" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

```python Python theme={null}
monitors = client.monitors.list().monitors
```

```typescript TypeScript theme={null}
const { monitors } = await client.monitors.list();
```

The list response wraps Monitor objects in a `monitors` array. To retrieve one Monitor:

```bash cURL theme={null}
curl "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

```python Python theme={null}
monitor = client.monitors.get(monitor_id)
```

```typescript TypeScript theme={null}
const monitor = await client.monitors.get(monitorId);
```

Saved run history is currently available in the dashboard. The REST API returns the baseline from
creation and the result of each run-now request, but does not provide a run-history list endpoint.

## Pause or Resume

Send a status-only update. `active` resumes the schedule and `paused` stops future scheduled runs
without removing history.

```bash cURL theme={null}
curl -X PATCH "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'
```

```python Python theme={null}
client.monitors.pause(monitor_id)
client.monitors.resume(monitor_id)
```

```typescript TypeScript theme={null}
await client.monitors.pause(monitorId);
await client.monitors.resume(monitorId);
```

## Edit a Monitor

Send only the fields you want to change: `schedule_cron`, `name`, `purpose`, or `webhook_url`.
Omitted fields keep their existing values, and `null` clears the name, purpose, or webhook URL.
Send at least one field.

```bash theme={null}
curl -X PATCH "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekday pricing"}'
```

The SDKs' `update` methods still take `schedule_cron`. To change several fields at once:

```bash cURL theme={null}
curl -X PATCH "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_cron": "CRON_TZ=America/Los_Angeles 0 8 * * 1-5",
    "name": "Weekday pricing",
    "purpose": "The enterprise plan price changes",
    "webhook_url": null
  }'
```

```python Python theme={null}
client.monitors.update(
    monitor_id,
    schedule_cron="CRON_TZ=America/Los_Angeles 0 8 * * 1-5",
    name="Weekday pricing",
    purpose="The enterprise plan price changes",
    webhook_url=None,  # None clears; omit a field to keep it
)
```

```typescript TypeScript theme={null}
await client.monitors.update(monitorId, {
  schedule_cron: "CRON_TZ=America/Los_Angeles 0 8 * * 1-5",
  name: "Weekday pricing",
  purpose: "The enterprise plan price changes",
  webhook_url: null,
});
```

The target type and its `config` cannot be changed after creation. Create a new Monitor to watch a
different page or topic.

> [!WARNING]
>
> Do not combine `status` with schedule or metadata fields in one request. Send lifecycle and edit
> updates separately.

## Run Now

```bash cURL theme={null}
curl -X POST "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID/runs" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

```python Python theme={null}
run = client.monitors.run(monitor_id).run
```

```typescript TypeScript theme={null}
const { run } = await client.monitors.run(monitorId);
```

The response is `201 Created` with the Page Fetch result or Topic Search result under `run`. Run now
works for active, paused, and failed Monitors.

A Topic Monitor run can return `409 Conflict` with `error.code` set to `RETRY_REQUIRED` when the run
could not be created. Retry the request.

> [!NOTE]
>
> Run now records the result but does not send webhook or email notifications. Those delivery paths
> run only for scheduled checks.

## Delete a Monitor

```bash cURL theme={null}
curl -X DELETE "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

```python Python theme={null}
client.monitors.cancel(monitor_id)
```

```typescript TypeScript theme={null}
await client.monitors.cancel(monitorId);
```

Deleting a Monitor permanently removes the Monitor and its schedule. Its run history is no longer
available from Monitor.

```json theme={null}
{
  "deleted": true,
  "id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7"
}
```

## Scheduled Webhook Payloads

Webhooks are sent for every scheduled run, including runs with no changes. Page payloads include a
`fetch_monitor_id`; Topic payloads include a `search_monitor_id`.

> [tab] Page
>
> ```json theme={null}
> {
>   "fetch_monitor_id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
>   "id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
>   "is_baseline": false,
>   "outcome": "changed",
>   "diff": "diff --git a/Previous b/Current\n===================================================================\n--- a/Previous\n+++ b/Current\n@@ -1,2 +1,2 @@\n # Pricing\n-Pro: $20/month\n+Pro: $25/month\n",
>   "diff_truncated": false,
>   "judgment": {
>     "purpose": "The Pro plan price changes",
>     "is_relevant": true,
>     "summary": "The Pro plan went from $20 to $25 per month.",
>     "error": null
>   },
>   "results": [
>     {
>       "url": "https://example.com/pricing",
>       "final_url": "https://example.com/pricing",
>       "title": "Pricing",
>       "description": null,
>       "language": "en",
>       "format": "markdown",
>       "text": "# Pricing\nPro: $25/month",
>       "author": null,
>       "published_date": null,
>       "latency_ms": 398
>     }
>   ],
>   "errors": []
> }
> ```
>
> * `outcome` is `changed` or `unchanged` compared with the previous run. It is `baseline` when
>   there is no previous run to compare with, such as the first run.
> * `diff` is a unified diff against the previous run. It is `null` for `baseline` and
>   `unchanged` runs.
> * `diff_truncated` is `true` when the diff was cut at a line to keep the payload under 1 MB.
>   Open the run in the dashboard for the full diff.
> * `judgment` checks the change against the Monitor's purpose. It is `null` for `baseline` and
>   `unchanged` runs, and when the Monitor has no purpose. `summary` is set only when
>   `is_relevant` is `true`. When the check fails, `is_relevant` is `null` and `error` is set.
> * `results` holds the full page content for every run.

> [tab] Topic
>
> ```json theme={null}
> {
>   "search_monitor_id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
>   "id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
>   "request_id": "search-monitor:e047c12d:scheduled:message-id",
>   "query": "new electric vehicle policies",
>   "status_code": 200,
>   "result_count": 1,
>   "results": [
>     {
>       "position": 1,
>       "site_name": "example.gov",
>       "title": "New electric vehicle policy",
>       "snippet": "The policy takes effect next year.",
>       "url": "https://example.gov/ev-policy"
>     }
>   ],
>   "new_result_positions": [],
>   "created_at": "2026-09-09T16:00:00.000Z"
> }
> ```

Webhook delivery is best effort and retried up to three times. A delivery failure does not change
the completed Monitor run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.