Skip to content
watchdogβStart free

Developer documentation

Connect your first Python job.

Create a job, install the Python SDK, send your first run and test an email alert. Detailed monitoring options are linked after setup.

Code and examples reviewed

You need Python 3.10+ and a free Watchdog account. This synthetic example makes no model calls.

1. Create a job.

  1. Sign up, verify your email, and open your dashboard.
  2. Register an unscheduled job with slug daily-report. Choose Basic setup and a 60-second maximum runtime. Leave optional checks and recovery off.
  3. In Connect, create a telemetry API key for this workspace.

2. Install the SDK.

Install watchdog-agent-sdk 0.2.0 from PyPI. These commands use macOS, Linux or WSL; on Windows, activate with .venv\Scripts\Activate.ps1.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install watchdog-agent-sdk==0.2.0

3. Run a small example.

Save this as watchdog_check.py. The prompt accepts your telemetry key without displaying it or saving it in the file.

from getpass import getpass
from watchdog_agent import Watchdog

with Watchdog(
    api_key=getpass("Telemetry key: "),
    base_url="https://withwatchdog.com",
) as watchdog:
    with watchdog.run("daily-report", cancellable=False):
        print("Synthetic job completed")
python watchdog_check.py

4. Confirm the run arrived.

Open Runs in the dashboard. Find daily-report and confirm its successful status, run.started and run.completed events. Printed output alone does not prove delivery.

If it is missing or shows a coverage warning, check the job slug and workspace key, then follow telemetry troubleshooting.

To connect your real job, replace the print statement and set a realistic runtime limit. Progress monitoring stays opt-in. For unattended use, set WATCHDOG_URL and WATCHDOG_API_KEY through your environment or secret manager; Watchdog() reads them.

5. Send a test alert.

  1. Open Settings → Email alerts. Use your verified account email, or confirm another recipient through its email link.
  2. Click Send test alert. Watchdog supplies the sender; no email-provider account or credentials are needed.
  3. Allow at least a minute, then check your inbox and spam folder. Queued means pending; Accepted by email provider is not confirmed inbox receipt. A failed attempt shows Failed.

Email or setup trouble? Contact support →

Next steps.