Create a Monitor

curl --request POST \
  --url https://api.spidra.io/api/monitors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Dentists in Lekki",
  "sources": [
    {
      "kind": "template",
      "template": "google-maps-leads",
      "inputs": {
        "query": "dentist",
        "areas": [
          "Lekki, Lagos"
        ]
      }
    }
  ],
  "schedule": {
    "every": "1d",
    "at": "08:00",
    "timezone": "Africa/Lagos"
  },
  "alertOn": "new",
  "notify": {
    "email": {
      "enabled": true
    }
  }
}
'

import requests

url = "https://api.spidra.io/api/monitors"

payload = {
    "name": "Dentists in Lekki",
    "sources": [
        {
            "kind": "template",
            "template": "google-maps-leads",
            "inputs": {
                "query": "dentist",
                "areas": ["Lekki, Lagos"]
            }
        }
    ],
    "schedule": {
        "every": "1d",
        "at": "08:00",
        "timezone": "Africa/Lagos"
    },
    "alertOn": "new",
    "notify": { "email": { "enabled": True } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Dentists in Lekki',
    sources: [
      {
        kind: 'template',
        template: 'google-maps-leads',
        inputs: {query: 'dentist', areas: ['Lekki, Lagos']}
      }
    ],
    schedule: {every: '1d', at: '08:00', timezone: 'Africa/Lagos'},
    alertOn: 'new',
    notify: {email: {enabled: true}}
  })
};

fetch('https://api.spidra.io/api/monitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spidra.io/api/monitors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Dentists in Lekki',
    'sources' => [
        [
                'kind' => 'template',
                'template' => 'google-maps-leads',
                'inputs' => [
                                'query' => 'dentist',
                                'areas' => [
                                                                'Lekki, Lagos'
                                ]
                ]
        ]
    ],
    'schedule' => [
        'every' => '1d',
        'at' => '08:00',
        'timezone' => 'Africa/Lagos'
    ],
    'alertOn' => 'new',
    'notify' => [
        'email' => [
                'enabled' => true
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spidra.io/api/monitors"

	payload := strings.NewReader("{\n  \"name\": \"Dentists in Lekki\",\n  \"sources\": [\n    {\n      \"kind\": \"template\",\n      \"template\": \"google-maps-leads\",\n      \"inputs\": {\n        \"query\": \"dentist\",\n        \"areas\": [\n          \"Lekki, Lagos\"\n        ]\n      }\n    }\n  ],\n  \"schedule\": {\n    \"every\": \"1d\",\n    \"at\": \"08:00\",\n    \"timezone\": \"Africa/Lagos\"\n  },\n  \"alertOn\": \"new\",\n  \"notify\": {\n    \"email\": {\n      \"enabled\": true\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spidra.io/api/monitors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Dentists in Lekki\",\n  \"sources\": [\n    {\n      \"kind\": \"template\",\n      \"template\": \"google-maps-leads\",\n      \"inputs\": {\n        \"query\": \"dentist\",\n        \"areas\": [\n          \"Lekki, Lagos\"\n        ]\n      }\n    }\n  ],\n  \"schedule\": {\n    \"every\": \"1d\",\n    \"at\": \"08:00\",\n    \"timezone\": \"Africa/Lagos\"\n  },\n  \"alertOn\": \"new\",\n  \"notify\": {\n    \"email\": {\n      \"enabled\": true\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spidra.io/api/monitors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Dentists in Lekki\",\n  \"sources\": [\n    {\n      \"kind\": \"template\",\n      \"template\": \"google-maps-leads\",\n      \"inputs\": {\n        \"query\": \"dentist\",\n        \"areas\": [\n          \"Lekki, Lagos\"\n        ]\n      }\n    }\n  ],\n  \"schedule\": {\n    \"every\": \"1d\",\n    \"at\": \"08:00\",\n    \"timezone\": \"Africa/Lagos\"\n  },\n  \"alertOn\": \"new\",\n  \"notify\": {\n    \"email\": {\n      \"enabled\": true\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "monitor": {
    "id": "<string>",
    "name": "<string>",
    "status": "active",
    "sources": [
      {
        "kind": "template",
        "id": "<string>",
        "label": "<string>",
        "template": "<string>",
        "inputs": {},
        "presetId": "<string>",
        "urls": [
          "<string>"
        ]
      }
    ],
    "schedule": {
      "every": "5m",
      "at": "<string>",
      "day": 3,
      "cron": "<string>",
      "timezone": "<string>"
    },
    "cron": "<string>",
    "alertOn": "<string>",
    "watchFields": [
      "<string>"
    ],
    "rule": {
      "field": "<string>",
      "op": "lt",
      "value": 123
    },
    "goal": "<string>",
    "notify": {
      "email": {
        "enabled": true,
        "recipients": [
          "<string>"
        ]
      },
      "webhook": {
        "url": "<string>",
        "secret": "<string>"
      },
      "slack": {
        "webhookUrl": "<string>"
      },
      "discord": {
        "webhookUrl": "<string>"
      }
    },
    "nextRunAt": "2023-11-07T05:31:56Z",
    "lastCheckAt": "2023-11-07T05:31:56Z",
    "lastChangeAt": "2023-11-07T05:31:56Z",
    "lastStatus": "<string>",
    "lastSummary": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "recipients": [
    {
      "email": "<string>",
      "status": "pending"
    }
  ]
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "code": "INVALID_INPUT",
  "message": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

POST

monitors

Create a Monitor

curl --request POST \
  --url https://api.spidra.io/api/monitors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Dentists in Lekki",
  "sources": [
    {
      "kind": "template",
      "template": "google-maps-leads",
      "inputs": {
        "query": "dentist",
        "areas": [
          "Lekki, Lagos"
        ]
      }
    }
  ],
  "schedule": {
    "every": "1d",
    "at": "08:00",
    "timezone": "Africa/Lagos"
  },
  "alertOn": "new",
  "notify": {
    "email": {
      "enabled": true
    }
  }
}
'

import requests

url = "https://api.spidra.io/api/monitors"

payload = {
    "name": "Dentists in Lekki",
    "sources": [
        {
            "kind": "template",
            "template": "google-maps-leads",
            "inputs": {
                "query": "dentist",
                "areas": ["Lekki, Lagos"]
            }
        }
    ],
    "schedule": {
        "every": "1d",
        "at": "08:00",
        "timezone": "Africa/Lagos"
    },
    "alertOn": "new",
    "notify": { "email": { "enabled": True } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Dentists in Lekki',
    sources: [
      {
        kind: 'template',
        template: 'google-maps-leads',
        inputs: {query: 'dentist', areas: ['Lekki, Lagos']}
      }
    ],
    schedule: {every: '1d', at: '08:00', timezone: 'Africa/Lagos'},
    alertOn: 'new',
    notify: {email: {enabled: true}}
  })
};

fetch('https://api.spidra.io/api/monitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spidra.io/api/monitors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Dentists in Lekki',
    'sources' => [
        [
                'kind' => 'template',
                'template' => 'google-maps-leads',
                'inputs' => [
                                'query' => 'dentist',
                                'areas' => [
                                                                'Lekki, Lagos'
                                ]
                ]
        ]
    ],
    'schedule' => [
        'every' => '1d',
        'at' => '08:00',
        'timezone' => 'Africa/Lagos'
    ],
    'alertOn' => 'new',
    'notify' => [
        'email' => [
                'enabled' => true
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spidra.io/api/monitors"

	payload := strings.NewReader("{\n  \"name\": \"Dentists in Lekki\",\n  \"sources\": [\n    {\n      \"kind\": \"template\",\n      \"template\": \"google-maps-leads\",\n      \"inputs\": {\n        \"query\": \"dentist\",\n        \"areas\": [\n          \"Lekki, Lagos\"\n        ]\n      }\n    }\n  ],\n  \"schedule\": {\n    \"every\": \"1d\",\n    \"at\": \"08:00\",\n    \"timezone\": \"Africa/Lagos\"\n  },\n  \"alertOn\": \"new\",\n  \"notify\": {\n    \"email\": {\n      \"enabled\": true\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spidra.io/api/monitors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Dentists in Lekki\",\n  \"sources\": [\n    {\n      \"kind\": \"template\",\n      \"template\": \"google-maps-leads\",\n      \"inputs\": {\n        \"query\": \"dentist\",\n        \"areas\": [\n          \"Lekki, Lagos\"\n        ]\n      }\n    }\n  ],\n  \"schedule\": {\n    \"every\": \"1d\",\n    \"at\": \"08:00\",\n    \"timezone\": \"Africa/Lagos\"\n  },\n  \"alertOn\": \"new\",\n  \"notify\": {\n    \"email\": {\n      \"enabled\": true\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spidra.io/api/monitors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Dentists in Lekki\",\n  \"sources\": [\n    {\n      \"kind\": \"template\",\n      \"template\": \"google-maps-leads\",\n      \"inputs\": {\n        \"query\": \"dentist\",\n        \"areas\": [\n          \"Lekki, Lagos\"\n        ]\n      }\n    }\n  ],\n  \"schedule\": {\n    \"every\": \"1d\",\n    \"at\": \"08:00\",\n    \"timezone\": \"Africa/Lagos\"\n  },\n  \"alertOn\": \"new\",\n  \"notify\": {\n    \"email\": {\n      \"enabled\": true\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "monitor": {
    "id": "<string>",
    "name": "<string>",
    "status": "active",
    "sources": [
      {
        "kind": "template",
        "id": "<string>",
        "label": "<string>",
        "template": "<string>",
        "inputs": {},
        "presetId": "<string>",
        "urls": [
          "<string>"
        ]
      }
    ],
    "schedule": {
      "every": "5m",
      "at": "<string>",
      "day": 3,
      "cron": "<string>",
      "timezone": "<string>"
    },
    "cron": "<string>",
    "alertOn": "<string>",
    "watchFields": [
      "<string>"
    ],
    "rule": {
      "field": "<string>",
      "op": "lt",
      "value": 123
    },
    "goal": "<string>",
    "notify": {
      "email": {
        "enabled": true,
        "recipients": [
          "<string>"
        ]
      },
      "webhook": {
        "url": "<string>",
        "secret": "<string>"
      },
      "slack": {
        "webhookUrl": "<string>"
      },
      "discord": {
        "webhookUrl": "<string>"
      }
    },
    "nextRunAt": "2023-11-07T05:31:56Z",
    "lastCheckAt": "2023-11-07T05:31:56Z",
    "lastChangeAt": "2023-11-07T05:31:56Z",
    "lastStatus": "<string>",
    "lastSummary": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "recipients": [
    {
      "email": "<string>",
      "status": "pending"
    }
  ]
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

{
  "status": "error",
  "code": "INVALID_INPUT",
  "message": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

A monitor runs its sources on a schedule, compares each check with the previous one, and alerts you when something changed. The Monitors guide explains each option; this page shows the request.

Example request

Watch Google Maps for new dentists in Lekki, every morning at 8:

curl -X POST https://api.spidra.io/api/monitors \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dentists in Lekki",
    "sources": [
      { "kind": "template", "template": "google-maps-leads", "inputs": { "query": "dentist", "areas": ["Lekki, Lagos"] } }
    ],
    "schedule": { "every": "1d", "at": "08:00", "timezone": "Africa/Lagos" },
    "alertOn": "new",
    "notify": { "email": { "enabled": true } }
  }'

const res = await fetch("https://api.spidra.io/api/monitors", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPIDRA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Dentists in Lekki",
    sources: [{ kind: "template", template: "google-maps-leads", inputs: { query: "dentist", areas: ["Lekki, Lagos"] } }],
    schedule: { every: "1d", at: "08:00", timezone: "Africa/Lagos" },
    alertOn: "new",
    notify: { email: { enabled: true } },
  }),
});
const { monitor } = await res.json();

import os, requests

res = requests.post(
    "https://api.spidra.io/api/monitors",
    headers={"Authorization": f"Bearer {os.environ['SPIDRA_API_KEY']}"},
    json={
        "name": "Dentists in Lekki",
        "sources": [{"kind": "template", "template": "google-maps-leads", "inputs": {"query": "dentist", "areas": ["Lekki, Lagos"]}}],
        "schedule": {"every": "1d", "at": "08:00", "timezone": "Africa/Lagos"},
        "alertOn": "new",
        "notify": {"email": {"enabled": True}},
    },
)
monitor = res.json()["monitor"]

Response

201 with the monitor. This one watches a single page for text changes, with email alerts off:

{
  "status": "success",
  "monitor": {
    "id": "d6761e12-b011-4633-a593-fa6be2ef466c",
    "name": "Docs test page",
    "status": "active",
    "sources": [{ "id": "ae22524a61ad", "kind": "urls", "urls": ["https://httpbin.org/uuid"], "label": "httpbin.org" }],
    "schedule": { "every": "1d", "at": "09:00", "timezone": "Africa/Lagos" },
    "cron": "0 9 * * *",
    "alertOn": "page",
    "watchFields": [],
    "rule": null,
    "goal": null,
    "notify": { "email": { "enabled": false } },
    "nextRunAt": "2026-10-25T08:00:00.000Z",
    "lastCheckAt": null,
    "lastChangeAt": null,
    "lastStatus": null,
    "lastSummary": null,
    "createdAt": "2026-10-24T18:50:07.000Z",
    "updatedAt": "2026-10-24T18:50:07.000Z"
  },
  "recipients": []
}

The first check runs straight away and records the starting point (“Started watching (1 item)”). It doesn’t alert. Send "checkNow": false to wait for the schedule instead. nextRunAt is in UTC. recipients lists any extra email addresses with their status. Each one gets a confirmation email and receives alerts only after confirming.

Sources

`kind`	Fields	Watches
`template`	`template`, `inputs`	A template’s rows. Each row has a stable key, so new, changed and removed items are exact.
`preset`	`presetId`	A saved scrape, batch, map, search or template preset.
`urls`	`urls` (up to 50)	Public pages.

Up to 10 sources per monitor. Each can have a label, shown in alerts.

Errors

Status	When
`422`	A field needs fixing. `errors` lists each one, for example `{ "field": "schedule", "message": "Your plan checks at most every 15 minutes." }` or `{ "field": "sources[0].urls[0]", "message": "\"http://localhost/x\" can't be a private or internal address." }`.
`403`	Your plan’s monitor limit is reached (`MONITOR_LIMIT`). Paused monitors count.
`409`	Another monitor is being created on your account at the same moment (`BUSY`). Try again.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name

string

Defaults to the first source's label.

sources

object[]

Required array length: 1 - 10 elements

Show child attributes

schedule

object

Your plan sets the shortest interval: daily on Free, hourly on Starter, every 15 minutes on Builder, every 5 minutes on Pro.

Show child attributes

alertOn

enum<string>

What counts as a change. Default page when every source is a URL list, otherwise new.

Available options:

new,

changed,

removed,

page,

every

watchFields

string[]

alertOn changed: only these fields count. Empty means every field.

Maximum array length: 20

rule

object | null

Only alert about items where this is true, for example { "field": "price", "op": "drops_by_pct", "value": 10 }.

Show child attributes

goal

string | null

Plain-language goal. When something changed, AI decides whether it matches before alerting, and says why.

Maximum string length: 1000

notify

object

Show child attributes

checkNow

boolean

default:true

Create only: run the first check straight away. It records the starting point and doesn't alert.

Response

Created.

status

enum<string>

Available options:

success

monitor

object

Show child attributes

recipients

object[]

Extra email recipients and whether they confirmed.

Show child attributes

Using the API

Scrape

Batch scrape

Crawl

Map

Search

Parse

Templates

Presets

Monitors

Logs

Account

Create a Monitor

Example request

Response

Sources

Errors

Authorizations

Body

Response

​Example request

​Response

​Sources

​Errors

Authorizations

Body

Response

Example request

Response

Sources

Errors