Skip to main content

watchfor (Python)

Official Python SDK + CLI for WatchFor — uptime & infrastructure monitoring (monitors, alert rules, incidents, maintenance windows) over the REST API. Zero dependencies (standard library only).

There is also a TypeScript SDK, an MCP server and an A2A agent for AI agents.

Install

pip install watchfor

Quick start

from watchfor import WatchFor

wf = WatchFor(api_key="wf_live_...")  # create keys in Settings → API keys

# One-call org snapshot
print(wf.summary())

# List monitors
for m in wf.monitors.list()["data"]:
    print(m["name"], m["status"])

# Create a monitor (idempotency key optional, for safe retries)
mon = wf.monitors.create(
    {
        "name": "example.com",
        "type": "http",
        "target": "https://example.com",
        "interval": 300,
        "locations": ["<location-id>"],  # from wf.locations()
    },
    idempotency_key="create-example-1",
)

# Diagnose: firing incidents right now
for inc in wf.incidents.list(status="firing")["data"]:
    print(inc["message"], inc["severity"])

# False positive? Keep the resolved incident on record but drop it from
# uptime, SLA, reports and the status page (include() undoes it)
wf.incidents.exclude(19351, reason="Probe-side DNS hiccup")

# Post-mortem: creates the draft on first use; only the sections you name change
wf.incidents.update_postmortem(19351, {
    "sections": {"summary": "Checkout returned 502 for 14 minutes."},
    "add_action_items": [{"title": "Validate upstreams in CI"}],
})

# Irreversible: wipe a monitor's checks and incidents; uptime restarts "since reset"
wf.monitors.reset(mon["id"])

# Page integrity: after a deploy, check the pages and accept what that check saw
wf.monitors.accept_baseline(integrity_monitor_id, fresh=True)

# MCP servers: before a release, keep tool drift quiet for 30 minutes (downtime still pages);
# a drift incident the user confirms was theirs is accepted as an expected change
wf.monitors.set_expected_change_window(mcp_monitor_id, window=30, note="v2.4 release")
wf.incidents.accept_expected_change(19352, note="New search tool shipped in v2.4")

# Browser checks: try a Playwright script once (nothing saved), then read the result
run = wf.playwright.test_run(script=script, target="https://shop.example.com")
wf.playwright.get_test_run(run["id"])  # status: queued | running | done | error
wf.variables.put("LOGIN_PASSWORD", value=password, secret=True)

# The same org secrets in HTTP/API/MCP checks: {{NAME}} in auth, a header or the body
wf.variables.put("API_TOKEN", value=token, secret=True)
wf.monitors.update(api_monitor_id, {"config": {"requestHeaders": [
    {"key": "Authorization", "value": "Bearer {{API_TOKEN}}"}]}})

# Older checks: pass next_cursor back as cursor (keep the same hours/success)
page = wf.monitors.checks(mon["id"], hours=24, limit=100)
if page["next_cursor"]:
    wf.monitors.checks(mon["id"], hours=24, limit=100, cursor=page["next_cursor"])

# Delete a contact group that alert rules still use (409 without force)
wf.contact_groups.delete("<group-id>", force=True)

# What the alerting engine sees right now: alerted, recovering 1/3, confirming 2 of 3…
state = wf.monitors.get(mon["id"])["alerting_state"]

# Response times on a real time axis (5-min buckets for 24h, 15 min for 7d)
up = wf.monitors.uptime(mon["id"], "24h", series=True)
for b in up.get("response_time_series", []):
    print(b["at"], b["avg_ms"])

# Game server: latency thresholds suggested from the monitor's own checks
sug = wf.monitors.suggested_thresholds("<game-monitor-id>")
for r in sug["regions"]:
    print(r["region"], r["p95_ms"], r["warning"], r["critical"])

# Pause up to 100 monitors at once; post a status-page announcement
wf.monitors.bulk("pause", ["<id-1>", "<id-2>"])
notice = wf.status_pages.create_announcement(
    "<page-id>", {"title": "Checkout errors", "body": "We are looking into it."}
)
wf.status_pages.update_announcement(
    "<page-id>", notice["id"], {"body": "Fixed.", "status": "resolved"}
)

Live diagnostics

Run any of 27 checks from WatchFor's probe fleet against any public target, monitored or not — this measures right now, rather than reading what WatchFor recorded:

# What can I run, and how much budget is left?
catalog = wf.diagnostics.list()

# One check, optionally from a location you choose (plan-gated)
dns = wf.diagnostics.run(
    "dns-lookup", "example.com", options={"recordType": "A", "resolver": "8.8.8.8"}
)
# A closed port, NXDOMAIN, expired certificate or unresolvable host does NOT
# raise — "success" is False and "error" says why ("result" keeps the raw answer):
if not dns["success"]:
    print("finding:", dns["error"])
print("runs left this hour:", dns["remaining"])

# Graded checks (tls-grade, http-headers, cwv-check, mcp-check, email-health,
# mail-server-check, cdn-check, smart-audit, dns-health, php-version-checker,
# software-exposure-checker) also return the
# dashboard's WatchFor Grade: letter, rubric id and what holds it down
headers = wf.diagnostics.run("http-headers", "https://example.com")
grade = headers.get("grade") or {}
if grade.get("letter"):
    print(f"grade {grade['letter']} ({grade['rubric']})")
    for cap in grade["capped_by"]:
        print(f"  max {cap['cap']}: {cap['title']} — fix: {cap['fix']}")
else:
    print("not graded:", grade.get("not_graded_reason"))

# The whole picture in one call: DNS + propagation + TLS + HTTP + ping
# from up to 3 regions, aggregated into one verdict
report = wf.diagnostics.diagnose_target("example.com")
print(report["verdict"]["status"], report["verdict"]["summary"])

Runs need a write key (a probe sends real traffic from WatchFor's IPs) and spend the same per-plan hourly allowance as the dashboard Toolbox. Details: https://watchfor.io/docs/api/diagnostics

Resource namespaces: wf.organizations, wf.monitors, wf.alert_rules, wf.incidents, wf.hosts, wf.status_pages, wf.on_call, wf.notification_channels, wf.maintenance_windows, wf.contacts, wf.contact_groups, wf.diagnostics, wf.playwright, wf.variables. Top-level: wf.summary(), wf.plan(), wf.me(), wf.locations(), wf.monitor_types(), wf.incident_stats(period=...), wf.report(...), wf.notifications(...), wf.activity(...), wf.batch([...]), wf.metrics(...).

Errors raise WatchForError with .status, .code, .message and .retry_after (seconds, on a 429). A non-JSON answer (an HTML page from a wrong base URL or a proxy) is a short http_error / invalid_response pointing at the base URL. base_url (and the CLI's WATCHFOR_BASE_URL) takes the origin (https://watchfor.io) or the full base (https://watchfor.io/api/v1) — the same value works for the npm and Ruby SDKs.

Organizations

An API key belongs to one organization. An OAuth access token acts as the user who approved it, so it reaches every organization that user belongs to; choose one with organization — the SDK sends it as the X-WatchFor-Organization header on every request:

wf = WatchFor(api_key=oauth_access_token)
for org in wf.organizations.list()["data"]:
    print(org["id"], org["name"], org["role"], org["is_default"], org["is_current"])

acme = WatchFor(api_key=oauth_access_token, organization="<organization-id>")
acme.me()  # {"organization": {"id", "name", "slug"}, "scope": ...}
other = acme.with_organization("<another-organization-id>")  # new client, same token
other.monitors.list()
  • organizations.list() returns the ids to use: every organization of the token's user with their role, is_default (used without organization) and is_current (what this client acts on). With an API key it returns just the key's own organization (role is None).
  • Without organization, an OAuth token acts on the user's oldest owned organization (else their oldest membership).
  • The user must be a member of that organization (otherwise 403 forbidden), and their role there applies: members read, acknowledge incidents and run diagnostics; changes need owner or admin.
  • With an API key leave it unset; it may only repeat the key's own organization id, and any other id is 403 forbidden (a key never switches organization).
  • with_organization(None) drops the header again.

Details: https://watchfor.io/docs/api/authentication#how-oauth-maps-to-your-data

Prometheus metrics (Pro plan and above)

text = wf.metrics(tag="production")  # Prometheus text format

Usually you point Prometheus at https://watchfor.io/api/v1/metrics directly; this is for scripts and one-off checks. See https://watchfor.io/docs/api/prometheus.

CLI

export WATCHFOR_API_KEY=wf_live_...
watchfor summary
watchfor monitors
watchfor incidents --status firing
watchfor checks <monitor_id> [--cursor <next_cursor>]
watchfor report --period 30d
watchfor me                       # which organization + scope
watchfor organizations            # ids for --organization

# OAuth token: pick the organization (before the command) or via the environment
export WATCHFOR_API_KEY=<oauth-access-token>
watchfor --organization <organization-id> monitors
WATCHFOR_ORGANIZATION=<organization-id> watchfor summary

Auth & scopes

Keys carry a scope: read (all GET endpoints) or write (read plus create/update/delete). See authentication. The API is also reachable with OAuth 2.1 access tokens (pass one as api_key; see Organizations).

Reference

MIT License.

Releasing

./publish.sh          # build, check, confirm, upload
./publish.sh --build  # build and check only

Debian and Ubuntu mark the system Python "externally managed" (PEP 668), so pip install build twine is refused and python3 -m build reports No module named build. The script keeps its own .venv-publish instead of touching the system Python. Credentials are read from ~/.pypirc as usual.

Metadata

Release files for watchfor 0.23.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for watchfor 0.23.0
File Size Uploaded Provenance Actions
watchfor-0.23.0.tar.gz 22.3 kB Without provenance Details for watchfor-0.23.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for watchfor 0.23.0
File Interpreter ABI Platform Actions
watchfor-0.23.0-py3-none-any.whl Python 3 none any Details for watchfor-0.23.0-py3-none-any.whl

Total release size: 41.8 kB

Release files / watchfor-0.23.0.tar.gz

Download URL watchfor-0.23.0.tar.gz
Size 22.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a5b396cd9008bef9cf9ab127ef7a076aaf8c481a636d9bb0d5d44cc766e2a184
BLAKE2b-256 checksum
How to use checksums
fae972806294734b528b241edc8ea49979dd6fa04093055e7ccff7c51b5c6b19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / watchfor-0.23.0-py3-none-any.whl

Download URL watchfor-0.23.0-py3-none-any.whl
Size 19.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
56d0893e22089e40be236795c243861867603afb25e258d4a9420f57c2f5bf6a
BLAKE2b-256 checksum
How to use checksums
706991344c6c8802220d191a60e3bfe6fe7882a7d9fb86b7a4625363d0cc22da
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for watchfor 0.23.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page