Skip to main content

​
Overview

The list command displays all URLs currently being monitored by Watchdog. It supports pagination and filtering by HTTP method, frequency, and status.

​
Usage

watchdog list [flags]

​
Aliases

  • ls

​
Description

The list command retrieves and displays all monitored URLs with their current status, configuration, and contact information. Results are paginated and can be filtered to help you find specific URLs.

​
Arguments

This command takes no arguments.

​
Flags

​
--page
integer
default:1
The page number to display. Use this to navigate through multiple pages of results.
​
--per_page
integer
default:20
The number of results to display per page.
​
--http_method
string
default:""
Filter results by HTTP method.Valid values:
  • get
  • post
  • put
  • patch
  • delete
​
--frequency
string
default:""
Filter results by monitoring frequency.Valid values:
  • ten_seconds
  • thirty_seconds
  • one_minute
  • five_minutes
  • thirty_minutes
  • one_hour
  • twelve_hours
  • twenty_four_hours
​
--status
string
default:""
Filter results by current health status.Valid values:
  • healthy - URL is reachable
  • unhealthy - URL is unreachable
  • pending - Not yet checked

​
Examples

​
List all monitored URLs

watchdog list
Expected output: 
Connected to PostgreSQL database!
Page 1 (showing 3 results)
------------------------------------------------------------
1. https://example.com
   ID: 1 | Method: get | Status: healthy | Frequency: five_minutes
   Contact: [email protected]

2. https://api.example.com/health
   ID: 2 | Method: post | Status: healthy | Frequency: one_minute
   Contact: [email protected]

3. https://critical-service.com
   ID: 3 | Method: get | Status: unhealthy | Frequency: ten_seconds
   Contact: [email protected]

------------------------------------------------------------
✓ End of results

​
Navigate to a specific page

watchdog list --page=2
Expected output: 
Page 2 (showing 20 results)
← Previous: --page=1 | → Next: --page=3
------------------------------------------------------------
...

​
Filter by status

watchdog list --status=unhealthy
Shows only URLs that are currently down.

​
Filter by HTTP method

watchdog list --http_method=post
Shows only URLs monitored with POST requests.

​
Filter by frequency

watchdog list --frequency=ten_seconds
Shows only URLs checked every 10 seconds.

​
Combine multiple filters

watchdog list --status=healthy --frequency=five_minutes --per_page=50
Shows healthy URLs checked every 5 minutes, with 50 results per page.

​
Using the short alias

watchdog ls --status=unhealthy

​
Output format

For each URL, the list command displays:
​
Position number
integer
The sequential number in the list (accounts for pagination offset)
​
URL
string
The full URL being monitored
​
ID
integer
The unique identifier (use with remove and analysis commands)
​
Method
string
The HTTP method used for health checks
​
Status
string
Current health status: healthy, unhealthy, or pending
​
Frequency
string
How often the URL is checked
​
Contact
string
Email address for alerts

​
Pagination

When there are more results than fit on one page:
  • The output shows ”← Previous” and ”→ Next” navigation hints
  • Use --page=N to navigate to a specific page
  • Adjust --per_page to control how many results appear per page
Page numbers start at 1. Using --page=0 or a negative number will result in an error.

​
Error handling

​
Invalid page number

watchdog list --page=0
Error output: 
page must be greater than 0

​
Invalid per_page number

watchdog list --per_page=-5
Error output: 
per_page must be greater than 0

​
Invalid HTTP method filter

watchdog list --http_method=head
Error output: 
failed to fetch URLs: invalid http method: head

​
Invalid frequency filter

watchdog list --frequency=two_minutes
Error output: 
failed to fetch URLs: invalid monitoring frequency: two_minutes

​
Invalid status filter

watchdog list --status=unknown
Error output: 
failed to fetch URLs: invalid site health option: unknown

​
No URLs found

If no URLs match your filters: 
No URLs found

​
Common use cases

​
Check for unhealthy services

watchdog list --status=unhealthy
Quickly identify all services that are currently down.

​
Review high-frequency monitors

watchdog list --frequency=ten_seconds
See which services are being monitored most frequently.

​
Find a URL by method

watchdog list --http_method=post --per_page=100
List all POST endpoints being monitored.

​
Export list with large page size

watchdog list --per_page=1000 > monitored-urls.txt
Get all URLs in a single page for documentation.

​
Technical details

  • Pagination uses offset-based queries
  • The command fetches per_page + 1 results to determine if more pages exist
  • Filters are applied at the database level for efficiency
  • Results maintain consistent ordering across pages

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us