Get single tag

cURL

curl -X GET "https://api.sitespy.app/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'
response = requests.get(f'https://api.sitespy.app/api/v1/tag/{tag_uuid}', headers=headers)
print(response.json())

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sitespy.app/api/v1/tag/{uuid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "date_created": 123,
  "owner_api_key": "<string>",
  "url": "<string>",
  "title": "<string>",
  "tag": "<string>",
  "tags": [
    "<string>"
  ],
  "paused": true,
  "paused_by": "plan_limit",
  "paused_at": 123,
  "notification_muted": true,
  "notification_rate_limit_per_hour": 1,
  "notification_rate_limit_per_day": 1,
  "method": "GET",
  "fetch_backend": "system",
  "headers": {},
  "body": "<string>",
  "proxy": "<string>",
  "ignore_status_codes": true,
  "webdriver_delay": 30,
  "disable_javascript": false,
  "mobile_view": false,
  "noise_reduction_ads": true,
  "webdriver_js_execute_code": "<string>",
  "time_between_check": {
    "weeks": 26000,
    "days": 182500,
    "hours": 4380000,
    "minutes": 262800000,
    "seconds": 15768000000
  },
  "time_between_check_use_default": true,
  "notification_urls": [
    "<string>"
  ],
  "notification_title": "<string>",
  "notification_body": "<string>",
  "notification_format": "text",
  "track_ldjson_price_data": true,
  "browser_steps": [
    {
      "operation": "<string>",
      "selector": "<string>",
      "optional_value": "<string>"
    }
  ],
  "processor": "text_json_diff",
  "screenshot_enabled": false,
  "include_filters": [
    "<string>"
  ],
  "subtractive_selectors": [
    "<string>"
  ],
  "ignore_text": [
    "<string>"
  ],
  "auto_ignore_text": [
    "<string>"
  ],
  "auto_noise_reduction_enabled": true,
  "trigger_text": [
    "<string>"
  ],
  "text_should_not_be_present": [
    "<string>"
  ],
  "alert_on_state_change": true,
  "extract_text": [
    "<string>"
  ],
  "trim_text_whitespace": false,
  "sort_text_alphabetically": false,
  "remove_duplicate_lines": false,
  "check_unique_lines": false,
  "strip_ignored_lines": true,
  "filter_text_added": true,
  "filter_text_removed": true,
  "filter_text_replaced": true,
  "in_stock_only": true,
  "follow_price_changes": true,
  "price_change_threshold_percent": 123,
  "has_ldjson_price_data": true,
  "notification_screenshot": false,
  "filter_failure_notification_send": true,
  "use_page_title_in_list": true,
  "history_snapshot_max_length": 500,
  "time_schedule_limit": {
    "enabled": false,
    "monday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "tuesday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "wednesday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "thursday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "friday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "saturday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "sunday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    }
  },
  "conditions": [
    {
      "field": "<string>",
      "operator": "<string>",
      "value": "<string>"
    }
  ],
  "conditions_match_logic": "ALL",
  "ai_alert_condition": "<string>",
  "last_ai_summary": "<string>",
  "last_ai_summary_from": 1,
  "last_ai_summary_to": 1,
  "last_filter_degraded_alert_ts": 1,
  "state_blocked": true,
  "state_last_transition_at": 1,
  "state_waiting_alert_ts": 1,
  "track_what": "<string>",
  "ai_tuning_started_at": 0,
  "filters_source": "manual",
  "overrides_watch": true
}

GET

tag

{uuid}

cURL

curl -X GET "https://api.sitespy.app/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'
response = requests.get(f'https://api.sitespy.app/api/v1/tag/{tag_uuid}', headers=headers)
print(response.json())

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sitespy.app/api/v1/tag/{uuid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "date_created": 123,
  "owner_api_key": "<string>",
  "url": "<string>",
  "title": "<string>",
  "tag": "<string>",
  "tags": [
    "<string>"
  ],
  "paused": true,
  "paused_by": "plan_limit",
  "paused_at": 123,
  "notification_muted": true,
  "notification_rate_limit_per_hour": 1,
  "notification_rate_limit_per_day": 1,
  "method": "GET",
  "fetch_backend": "system",
  "headers": {},
  "body": "<string>",
  "proxy": "<string>",
  "ignore_status_codes": true,
  "webdriver_delay": 30,
  "disable_javascript": false,
  "mobile_view": false,
  "noise_reduction_ads": true,
  "webdriver_js_execute_code": "<string>",
  "time_between_check": {
    "weeks": 26000,
    "days": 182500,
    "hours": 4380000,
    "minutes": 262800000,
    "seconds": 15768000000
  },
  "time_between_check_use_default": true,
  "notification_urls": [
    "<string>"
  ],
  "notification_title": "<string>",
  "notification_body": "<string>",
  "notification_format": "text",
  "track_ldjson_price_data": true,
  "browser_steps": [
    {
      "operation": "<string>",
      "selector": "<string>",
      "optional_value": "<string>"
    }
  ],
  "processor": "text_json_diff",
  "screenshot_enabled": false,
  "include_filters": [
    "<string>"
  ],
  "subtractive_selectors": [
    "<string>"
  ],
  "ignore_text": [
    "<string>"
  ],
  "auto_ignore_text": [
    "<string>"
  ],
  "auto_noise_reduction_enabled": true,
  "trigger_text": [
    "<string>"
  ],
  "text_should_not_be_present": [
    "<string>"
  ],
  "alert_on_state_change": true,
  "extract_text": [
    "<string>"
  ],
  "trim_text_whitespace": false,
  "sort_text_alphabetically": false,
  "remove_duplicate_lines": false,
  "check_unique_lines": false,
  "strip_ignored_lines": true,
  "filter_text_added": true,
  "filter_text_removed": true,
  "filter_text_replaced": true,
  "in_stock_only": true,
  "follow_price_changes": true,
  "price_change_threshold_percent": 123,
  "has_ldjson_price_data": true,
  "notification_screenshot": false,
  "filter_failure_notification_send": true,
  "use_page_title_in_list": true,
  "history_snapshot_max_length": 500,
  "time_schedule_limit": {
    "enabled": false,
    "monday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "tuesday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "wednesday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "thursday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "friday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "saturday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    },
    "sunday": {
      "enabled": true,
      "start_time": "00:00",
      "duration": {
        "hours": "24",
        "minutes": "00"
      }
    }
  },
  "conditions": [
    {
      "field": "<string>",
      "operator": "<string>",
      "value": "<string>"
    }
  ],
  "conditions_match_logic": "ALL",
  "ai_alert_condition": "<string>",
  "last_ai_summary": "<string>",
  "last_ai_summary_from": 1,
  "last_ai_summary_to": 1,
  "last_filter_degraded_alert_ts": 1,
  "state_blocked": true,
  "state_last_transition_at": 1,
  "state_waiting_alert_ts": 1,
  "track_what": "<string>",
  "ai_tuning_started_at": 0,
  "filters_source": "manual",
  "overrides_watch": true
}

Authorizations

x-api-key

string

header

required

API key for authentication. You can find your API key in the Site Spy dashboard under Settings → API.

Path Parameters

uuid

string<uuid>

required

Tag unique ID

Query Parameters

muted

enum<string>

Set mute state

Available options:

muted,

unmuted

recheck

enum<string>

Queue all web page change monitors (watches) with this tag for recheck

Available options:

true

Response

Tag information or operation result

uuid

string<uuid>

read-only

Unique identifier

date_created

integer | null

read-only

Unix timestamp of creation

owner_api_key

string | null

read-only

API key that owns this watch (multi-tenant isolation)

url

string<uri>

URL to monitor for changes

Maximum string length: 5000

title

string | null

Custom title for the web page change monitor (watch), not to be confused with page_title

Maximum string length: 5000

tag

string

Tag UUID to associate with this web page change monitor (watch)

Maximum string length: 5000

tags

string[]

Array of tag UUIDs

paused

boolean

Whether the web page change monitor (watch) is paused

paused_by

enum<string> | null

read-only

Non-null when paused=true was set automatically. Values:

plan_limit — owner exceeded their plan's watch cap; auto-deleted 30d after paused_at unless user upgrades or un-pauses.
reliability — persistent classified failure; retained until a user or administrator resumes it. Null means the watch was paused manually by the user (no auto-delete).

Available options:

plan_limit,

reliability,

null

paused_at

integer

read-only

Unix timestamp when auto-pause was applied. Starts the auto-delete clock for paused_by != null watches. 0 when never auto-paused.

notification_muted

boolean

Whether notifications are muted

notification_rate_limit_per_hour

integer | null

Per-watch cap on notifications sent per hour. null uses the system default, 0 means unlimited.

Required range: x >= 0

notification_rate_limit_per_day

integer | null

Per-watch cap on notifications sent per day. null uses the system default, 0 means unlimited.

Required range: x >= 0

method

enum<string>

HTTP method to use

Available options:

GET,

POST,

DELETE,

PUT

fetch_backend

string

default:system

Backend to use for fetching content. Common values:

system (default) - Use the system-wide default fetcher
html_requests - Fast requests-based fetcher
html_webdriver - Browser-based fetcher (Playwright/Puppeteer)
extra_browser_* - Custom browser configurations (if configured)
Plugin-provided fetchers (if installed)

Pattern: ^(system|html_requests|html_hybrid|html_webdriver|extra_browser_.+)$

headers

object

HTTP headers to include in requests

Show child attributes

body

string | null

HTTP request body

Maximum string length: 5000

proxy

string | null

Proxy configuration

Maximum string length: 5000

ignore_status_codes

boolean | null

Ignore HTTP status code errors (boolean or null)

webdriver_delay

integer | null

Seconds to wait after page load before extracting content (browser backends only). null uses the system default.

Required range: 0 <= x <= 60

disable_javascript

boolean

default:false

Render the page in the browser with JavaScript execution disabled. Forces a browser backend.

mobile_view

boolean

default:false

Render the page with a mobile viewport, device pixel ratio, touch support and a mobile User-Agent. Forces a browser backend.

noise_reduction_ads

boolean | null

Block ads and cookie banners for this watch; null inherits the account-level setting of the same name

webdriver_js_execute_code

string | null

JavaScript code to execute

Maximum string length: 5000

time_between_check

object

Time intervals between checks. All fields must be non-negative. At least one non-zero value required when not using default settings.

Show child attributes

time_between_check_use_default

boolean

default:true

Whether to use global settings for time between checks - defaults to true if not set

notification_urls

string[]

Notification URLs for this web page change monitor (watch). Maximum 100 URLs.

Maximum array length: 100

Maximum string length: 1000

notification_title

string | null

Custom notification title

Maximum string length: 5000

notification_body

string | null

Custom notification body

Maximum string length: 5000

notification_format

enum<string>

Format for notifications

Available options:

text,

html,

htmlcolor,

markdown,

System default

track_ldjson_price_data

boolean | null

Whether to track JSON-LD price data

browser_steps

object[]

Browser automation steps. Maximum 100 steps allowed.

Maximum array length: 100

Show child attributes

processor

enum<string>

default:text_json_diff

Optional processor mode to use for change detection. image_ssim_diff (screenshot monitoring) requires Pro plan. Defaults to text_json_diff if not specified.

Available options:

restock_diff,

text_json_diff,

image_ssim_diff

screenshot_enabled

boolean

default:false

When true, capture and store screenshots alongside text snapshots on each check. Requires Pro plan and fetch_backend set to a browser-based fetcher (e.g. html_webdriver).

include_filters

string[]

CSS/XPath selectors naming the part of the page this watch follows, and the only part that can trigger a notification. In the dashboard, the AI chat and the browser extension this is set by pointing at the page in the element picker rather than typed; the API accepts it directly. A watch with an empty list follows the whole page, which means every timestamp, banner and counter on it counts as a change. Selectors that the backend cannot compile are dropped on save rather than rejected.

Maximum array length: 100

Maximum string length: 5000

subtractive_selectors

string[]

CSS/XPath selectors to remove content from the page

Maximum array length: 100

Maximum string length: 5000

ignore_text

string[]

Text patterns to ignore in change detection

Maximum array length: 100

Maximum string length: 5000

auto_ignore_text

string[]

read-only

Reversible noise patterns applied by automatic watch-quality remediation

Maximum array length: 20

Maximum string length: 5000

auto_noise_reduction_enabled

boolean | null

Enable automatic noise reduction for this watch; null inherits the account smart-filter setting

trigger_text

string[]

Text/regex patterns that must be present to trigger a change

Maximum array length: 100

Maximum string length: 5000

text_should_not_be_present

string[]

Text that should NOT be present (triggers alert if found)

Maximum array length: 100

Maximum string length: 5000

alert_on_state_change

boolean | null

Notify on the check where text_should_not_be_present stops matching, and stay silent otherwise, instead of notifying on every page diff while it does not match. Null derives it: a watch with text_should_not_be_present is waiting for that message to clear unless its stated intent is a generic "any change".

extract_text

string[]

Regex patterns to extract specific text after filtering

Maximum array length: 100

Maximum string length: 5000

trim_text_whitespace

boolean

default:false

Strip leading/trailing whitespace from text

sort_text_alphabetically

boolean

default:false

Sort lines alphabetically before comparison

remove_duplicate_lines

boolean

default:false

Remove duplicate lines from content

check_unique_lines

boolean

default:false

Compare against all history for unique lines

strip_ignored_lines

boolean | null

Remove lines matching ignore patterns

filter_text_added

boolean

default:true

Include added text in change detection

filter_text_removed

boolean

default:true

Include removed text in change detection

filter_text_replaced

boolean

default:true

Include replaced text in change detection

in_stock_only

boolean

default:true

Only trigger on in-stock transitions (restock_diff processor)

follow_price_changes

boolean

default:true

Monitor and track price changes (restock_diff processor)

price_change_threshold_percent

number | null

Minimum price change percentage to trigger notification

has_ldjson_price_data

boolean | null

read-only

Whether page has LD-JSON price data (auto-detected)

notification_screenshot

boolean

default:false

Include screenshot in notifications (if supported by notification URL)

filter_failure_notification_send

boolean

default:true

Send notification when filters fail to match content

use_page_title_in_list

boolean | null

Display page title in watch list (null = use system default)

history_snapshot_max_length

integer | null

Maximum number of history snapshots to keep (null = use system default)

Required range: 1 <= x <= 1000

time_schedule_limit

object

Weekly schedule limiting when checks can run

Show child attributes

conditions

object[]

Array of condition rules for change detection logic (empty array when not set)

Maximum array length: 100

Show child attributes

conditions_match_logic

enum<string>

default:ALL

Logic operator - ALL (match all conditions) or ANY (match any condition)

Available options:

ALL,

ANY

ai_alert_condition

string | null

Plain-English condition for AI smart alerts (Pro+ only). When set, AI evaluates each change against this condition and suppresses notifications that don't match. Example - "Only notify me if the price drops below $50".

Maximum string length: 500

last_ai_summary

string | null

read-only

AI-generated plain-English summary of the most recent change (Pro+ only, read-only — generated automatically when a change is detected).

last_ai_summary_from

integer

read-only

The older of the two snapshot timestamps last_ai_summary was written from. The summary describes one change, so a client rendering it beside a diff must check that this pair is the pair being shown — otherwise it captions one change with another change's summary. 0 means the pair was not recorded (a summary written before this field existed), in which case the summary is only trustworthy against the watch's newest pair.

Required range: x >= 0

last_ai_summary_to

integer

read-only

The newer of the two snapshot timestamps last_ai_summary was written from. 0 when not recorded.

Required range: x >= 0

last_filter_degraded_alert_ts

integer

read-only

When the owner was last told this watch's filters had degraded.

Required range: x >= 0

state_blocked

boolean | null

read-only

The state gate's verdict at the previous check; null before the first one.

state_last_transition_at

integer

read-only

When the state gate last changed its verdict.

Required range: x >= 0

state_waiting_alert_ts

integer

read-only

When the owner was last sent a "still waiting" note.

Required range: x >= 0

track_what

string | null

User's monitoring intent, e.g. "price changes", "new job listings". Set by the add-watch form or AI chat when the user describes what they want to track.

Maximum string length: 500

ai_tuning_started_at

integer

default:0

Unix timestamp set while an automatic filter repair is running for this watch, and zero when it is not. Lets the dashboard show the work as watch state that survives a page refresh.

filters_source

enum<string>

default:manual

Who chose this watch's include filter - 'manual' for a person, 'smart' for the removed smart-configure generator. It decides what happens when the include filter stops matching: a person's selector raises an error, a machine's silently falls back to the whole page. Nothing writes 'smart' any more, and watches configured before it was removed still carry the value with their filters honoured unchanged - but an edit that changes include_filters now records 'manual', since whoever made that edit chose the selector. Send the field explicitly to override that.

Available options:

manual,

smart

overrides_watch

boolean | null

Whether this tag's settings override watch settings for all watches in this tag/group.

true: Tag settings override watch settings
false: Tag settings do not override (watches use their own settings)
null: Not decided yet / inherit default behavior

Getting Started

Endpoints

Authorizations

Path Parameters

Query Parameters

Response