−50%

50% off your first month on any paid plan · code WELCOME50 · until Nov 30

Start free →

Domain Monitors

Domain Expiration Monitors

Domain expiration monitors track the expiration dates of your domains and warn you before they expire. The API lets you create, list, update, and delete domain monitors programmatically.

List domain monitors

GET /api/v1/domain-monitors

Returns a paginated list of all domain monitors in the project associated with your API key.

Query parameters

ParameterTypeDefaultDescription
statusstring—Filter by status (ok, warning, critical, unknown)
per_pageinteger25Results per page
pageinteger1Page number
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/domain-monitors?status=warning&per_page=10"
$response = Http::withToken('YOUR_API_KEY')
    ->get('https://watchcron.com/api/v1/domain-monitors', [
        'status'   => 'warning',
        'per_page' => 10,
    ]);

$monitors = $response->json('data');
import requests

response = requests.get(
    "https://watchcron.com/api/v1/domain-monitors",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"status": "warning", "per_page": 10},
)

monitors = response.json()["data"]
const response = await fetch(
  "https://watchcron.com/api/v1/domain-monitors?status=warning&per_page=10",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data: monitors } = await response.json();
req, _ := http.NewRequest("GET",
    "https://watchcron.com/api/v1/domain-monitors?status=warning&per_page=10", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response 200 OK

JSON
{
  "data": [
    {
      "uuid": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "domain": "example.com",
      "registrar": "Cloudflare, Inc.",
      "status": "ok",
      "expires_at": "2027-11-15T00:00:00Z",
      "days_until_expiry": 385,
      "warn_before_days": 30,
      "is_active": true,
      "last_checked_at": "2026-10-26T08:00:00Z",
      "last_error": null,
      "created_at": "2026-06-10T12:00:00Z",
      "updated_at": "2026-10-26T08:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 8,
      "per_page": 10,
      "current_page": 1,
      "last_page": 1
    }
  }
}

Domain monitor object

Every domain monitor response includes these fields:

FieldTypeDescription
uuidstringUnique identifier (UUID v4). Used in all API URLs.
domainstringThe domain name being monitored (e.g. example.com)
registrarstring|nullDomain registrar name, detected automatically via WHOIS
statusstringCurrent status: ok, warning, critical, or unknown
expires_atstring|nullISO 8601 expiration date of the domain
days_until_expiryinteger|nullNumber of days remaining until the domain expires
warn_before_daysintegerAlert threshold — triggers a warning this many days before expiration
is_activebooleanWhether monitoring is active
last_checked_atstring|nullISO 8601 timestamp of the most recent WHOIS check
last_errorstring|nullError message from the last failed check, if any
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Status values

StatusMeaning
okDomain expiration is more than warn_before_days away
warningDomain expires within warn_before_days — renewal recommended
criticalDomain has expired or expires within 7 days
unknownWHOIS lookup failed — expiration date could not be determined

Create a domain monitor

POST /api/v1/domain-monitors

Request body

FieldTypeRequiredDescription
domainstringYesDomain name to monitor (max 255 characters)
warn_before_daysintegerNoDays before expiration to trigger warning (1–365, default: 30)
Automatic detection: After creating a domain monitor, WatchCron performs an initial WHOIS lookup to detect the registrar, expiration date, and current status. The registrar, expires_at, and days_until_expiry fields are populated automatically.
curl -X POST https://watchcron.com/api/v1/domain-monitors \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "domain": "example.com",
       "warn_before_days": 30
     }'
$response = Http::withToken('YOUR_API_KEY')
    ->post('https://watchcron.com/api/v1/domain-monitors', [
        'domain'           => 'example.com',
        'warn_before_days' => 30,
    ]);

$monitor = $response->json('data');
import requests

response = requests.post(
    "https://watchcron.com/api/v1/domain-monitors",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "domain": "example.com",
        "warn_before_days": 30,
    },
)

monitor = response.json()["data"]
const response = await fetch("https://watchcron.com/api/v1/domain-monitors", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    domain: "example.com",
    warn_before_days: 30,
  }),
});

const { data: monitor } = await response.json();
body := strings.NewReader(`{
  "domain": "example.com",
  "warn_before_days": 30
}`)

req, _ := http.NewRequest("POST", "https://watchcron.com/api/v1/domain-monitors", body)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response 201 Created

JSON
{
  "data": {
    "uuid": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "domain": "example.com",
    "registrar": null,
    "status": "unknown",
    "expires_at": null,
    "days_until_expiry": null,
    "warn_before_days": 30,
    "is_active": true,
    "last_checked_at": null,
    "last_error": null,
    "created_at": "2026-10-26T10:00:00Z",
    "updated_at": "2026-10-26T10:00:00Z"
  }
}

Validation errors

If the domain is missing or invalid, the API returns 422:

422 response
{
  "error": "The domain field is required."
}

Get a domain monitor

GET /api/v1/domain-monitors/{uuid}

Returns full details for a single domain monitor.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/domain-monitors/e5f6a7b8-c9d0-1234-efab-345678901234"
$uuid = 'e5f6a7b8-c9d0-1234-efab-345678901234';

$response = Http::withToken('YOUR_API_KEY')
    ->get("https://watchcron.com/api/v1/domain-monitors/{$uuid}");

$monitor = $response->json('data');
uuid = "e5f6a7b8-c9d0-1234-efab-345678901234"

response = requests.get(
    f"https://watchcron.com/api/v1/domain-monitors/{uuid}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

monitor = response.json()["data"]
const uuid = "e5f6a7b8-c9d0-1234-efab-345678901234";

const response = await fetch(
  `https://watchcron.com/api/v1/domain-monitors/${uuid}`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data: monitor } = await response.json();

Returns the same domain monitor object as shown in Domain monitor object. Returns 404 if the UUID does not exist or belongs to a different project.

Update a domain monitor

PUT /api/v1/domain-monitors/{uuid}

Updates one or more fields on an existing domain monitor. Only include the fields you want to change — all fields are optional.

Request body

FieldTypeDescription
domainstringDomain name (max 255 characters)
warn_before_daysintegerDays before expiration to trigger warning (1–365)
curl -X PUT https://watchcron.com/api/v1/domain-monitors/e5f6a7b8-c9d0-1234-efab-345678901234 \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "warn_before_days": 60
     }'
$response = Http::withToken('YOUR_API_KEY')
    ->put("https://watchcron.com/api/v1/domain-monitors/{$uuid}", [
        'warn_before_days' => 60,
    ]);
response = requests.put(
    f"https://watchcron.com/api/v1/domain-monitors/{uuid}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "warn_before_days": 60,
    },
)
const response = await fetch(`https://watchcron.com/api/v1/domain-monitors/${uuid}`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    warn_before_days: 60,
  }),
});

Returns 200 OK with the updated domain monitor object.

Delete a domain monitor

DELETE /api/v1/domain-monitors/{uuid}

Permanently deletes a domain monitor.

curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/domain-monitors/e5f6a7b8-c9d0-1234-efab-345678901234"
$response = Http::withToken('YOUR_API_KEY')
    ->delete("https://watchcron.com/api/v1/domain-monitors/{$uuid}");
response = requests.delete(
    f"https://watchcron.com/api/v1/domain-monitors/{uuid}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
const response = await fetch(
  `https://watchcron.com/api/v1/domain-monitors/${uuid}`,
  {
    method: "DELETE",
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  }
);

Returns 204 No Content on success. This action is irreversible.

Pricing Docs
Log in Start free →