Monitor API Reference

Beta: Monitor is currently in beta and enabled per account. Contact support to request access.

Base URL

https://agent.tinyfish.ai

All requests require an X-API-Key header. See Authentication.

Monitor must be enabled for the API key’s account. The API returns 404 when it is unavailable.

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

Page
Topic

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"
  }'

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"
  }'

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

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

string

required

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

object

required

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

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.

string

Optional Monitor name, up to 100 characters.

string

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

string

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

Email delivery is currently configured in the dashboard. The REST API does not accept email settings.

Page Config

string

required

Public HTTP or HTTPS webpage URL.

string

default:"json"

Extracted content format: json, markdown, or html.

boolean

default:"false"

Include links found on the webpage.

boolean

default:"false"

Include image links found on the webpage.

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

string

required

Search query to repeat, up to 2000 characters.

integer

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

integer

default:"10"

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

List and Get Monitors

curl "https://agent.tinyfish.ai/v1/monitors" \
  -H "X-API-Key: $TINYFISH_API_KEY"

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

curl "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"

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.

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"}'

Edit a Monitor

Schedule edits must include schedule_cron. You can also replace or clear the name, purpose, and webhook URL. Omitted optional fields keep their existing values.

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

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

Do not combine status with schedule or metadata fields in one request. Send lifecycle and edit updates separately.

Run Now

curl -X POST "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID/runs" \
  -H "X-API-Key: $TINYFISH_API_KEY"

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.

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

Delete a Monitor

curl -X DELETE "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"

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

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

Page
Topic

{
  "fetch_monitor_id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
  "id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
  "is_baseline": false,
  "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": 398
    }
  ],
  "errors": []
}

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

Start Here

Agent API

Search API

Monitor (Beta)

Fetch API

Browser API

Research API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Base URL

Endpoints

Create a Monitor

Common Fields

Page Config

Topic Config

List and Get Monitors

Pause or Resume

Edit a Monitor

Run Now

Delete a Monitor

Scheduled Webhook Payloads

​Base URL

​Endpoints

​Create a Monitor

​Common Fields

​Page Config

​Topic Config

​List and Get Monitors

​Pause or Resume

​Edit a Monitor

​Run Now

​Delete a Monitor

​Scheduled Webhook Payloads

Base URL

Endpoints

Create a Monitor

Common Fields

Page Config

Topic Config

List and Get Monitors

Pause or Resume

Edit a Monitor

Run Now

Delete a Monitor

Scheduled Webhook Payloads