Cloud Cron
Cloud Cron Jobs
Cloud Cron jobs let you run HTTP requests on a schedule without managing a server. WatchCron handles the scheduling, execution, retries, and monitoring. Use the API to create, manage, and inspect Cloud Cron jobs programmatically.
List Cloud Cron jobs
/api/v1/cloud-crons
Returns a paginated list of all Cloud Cron jobs in the project associated with your API key.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | — | Filter by status (active, paused, failing) |
per_page | integer | 25 | Results per page |
page | integer | 1 | Page number |
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/cloud-crons?status=active&per_page=10"
$response = Http::withToken('YOUR_API_KEY') ->get('https://watchcron.com/api/v1/cloud-crons', [ 'status' => 'active', 'per_page' => 10, ]); $jobs = $response->json('data');
import requests response = requests.get( "https://watchcron.com/api/v1/cloud-crons", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"status": "active", "per_page": 10}, ) jobs = response.json()["data"]
const response = await fetch( "https://watchcron.com/api/v1/cloud-crons?status=active&per_page=10", { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: jobs } = await response.json();
req, _ := http.NewRequest("GET", "https://watchcron.com/api/v1/cloud-crons?status=active&per_page=10", nil) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 200 OK
{
"data": [
{
"uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "WordPress Cron Trigger",
"url": "https://example.com/wp-cron.php",
"method": "GET",
"status": "active",
"cron_expression": "*/5 * * * *",
"timezone": "UTC",
"timeout_seconds": 30,
"max_retries": 0,
"success_codes": null,
"success_keyword": null,
"prevent_overlap": false,
"is_running": false,
"is_active": true,
"consecutive_failures": 0,
"last_executed_at": "2026-10-26T12:05:00Z",
"next_execution_at": "2026-10-26T12:10:00Z",
"last_response_time_ms": 245,
"last_status_code": 200,
"last_error": null,
"maintenance_windows": null,
"created_at": "2026-10-01T08:00:00Z",
"updated_at": "2026-10-26T12:05:00Z"
}
],
"meta": {
"pagination": {
"total": 12,
"per_page": 10,
"current_page": 1,
"last_page": 2
}
}
}
Cloud Cron object
Every Cloud Cron response includes these fields:
| Field | Type | Description |
|---|---|---|
uuid | string | Unique identifier (UUID v4). Used in all API URLs. |
name | string | Display name of the job |
url | string | Target URL that will be requested on each execution |
method | string | HTTP method: GET, POST, PUT, PATCH, DELETE, or HEAD |
status | string | Current status: active, paused, or failing |
cron_expression | string | Standard 5-field cron expression defining the schedule |
timezone | string | IANA timezone for schedule evaluation (e.g. Europe/Berlin) |
timeout_seconds | integer | Maximum time in seconds to wait for a response (1–300) |
max_retries | integer | Number of retry attempts on failure (0–5) |
success_codes | array|null | List of HTTP status codes considered successful. If null, any 2xx is accepted. |
success_keyword | string|null | String that must appear (or be absent) in the response body for success |
prevent_overlap | boolean | If true, skips execution when the previous run is still in progress |
is_running | boolean | Whether the job is currently executing |
is_active | boolean | Whether the job is active (not paused) |
consecutive_failures | integer | Number of consecutive failed executions |
last_executed_at | string|null | ISO 8601 timestamp of the most recent execution |
next_execution_at | string|null | ISO 8601 timestamp of the next scheduled execution |
last_response_time_ms | integer|null | Response time in milliseconds of the last execution |
last_status_code | integer|null | HTTP status code returned by the last execution |
last_error | string|null | Error message from the last failed execution |
maintenance_windows | array|null | Scheduled maintenance windows during which execution is skipped |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Status values
| Status | Meaning |
|---|---|
active | Job is running on schedule — last execution succeeded |
paused | Job is paused — no executions or alerts will fire |
failing | Last execution failed — alert triggered |
Create a Cloud Cron job
/api/v1/cloud-crons
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Job name (max 255 characters) |
url | string | Yes | Target URL (max 2048 characters) |
method | string | No | GET, POST, PUT, PATCH, DELETE, or HEAD (default: GET) |
headers | array | No | Custom HTTP headers as key-value pairs |
body | string | No | Request body (for POST/PUT/PATCH methods) |
http_auth_user | string | No | HTTP Basic Auth username (max 255 characters) |
http_auth_pass | string | No | HTTP Basic Auth password (max 255 characters) |
cron_expression | string | Yes | Standard 5-field cron expression (max 100 characters) |
timezone | string | No | IANA timezone (max 64 characters, defaults to app timezone) |
timeout_seconds | integer | No | Request timeout in seconds, 1–300 (default: 30) |
max_retries | integer | No | Retry attempts on failure, 0–5 (default: 0) |
success_codes | array | No | List of HTTP status codes (100–599) considered successful |
success_keyword | string | No | String to match in the response body (max 255 characters) |
success_keyword_absent | boolean | No | If true, the keyword must be absent for success |
prevent_overlap | boolean | No | Skip execution if the previous run is still in progress |
maintenance_windows | array | No | Maintenance windows during which execution is skipped |
*/5 * * * * runs every 5 minutes, 0 2 * * * runs daily at 2 AM. Ranges, lists, and steps are supported.Example: schedule a WordPress cron trigger
curl -X POST https://watchcron.com/api/v1/cloud-crons \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "WordPress Cron Trigger", "url": "https://example.com/wp-cron.php", "method": "GET", "cron_expression": "*/5 * * * *", "timezone": "UTC", "timeout_seconds": 30, "max_retries": 2 }'
$response = Http::withToken('YOUR_API_KEY') ->post('https://watchcron.com/api/v1/cloud-crons', [ 'name' => 'WordPress Cron Trigger', 'url' => 'https://example.com/wp-cron.php', 'method' => 'GET', 'cron_expression' => '*/5 * * * *', 'timezone' => 'UTC', 'timeout_seconds' => 30, 'max_retries' => 2, ]); $job = $response->json('data'); echo "Next run: " . $job['next_execution_at'];
import requests response = requests.post( "https://watchcron.com/api/v1/cloud-crons", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "name": "WordPress Cron Trigger", "url": "https://example.com/wp-cron.php", "method": "GET", "cron_expression": "*/5 * * * *", "timezone": "UTC", "timeout_seconds": 30, "max_retries": 2, }, ) job = response.json()["data"] print(f"Next run: {job['next_execution_at']}")
const response = await fetch("https://watchcron.com/api/v1/cloud-crons", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ name: "WordPress Cron Trigger", url: "https://example.com/wp-cron.php", method: "GET", cron_expression: "*/5 * * * *", timezone: "UTC", timeout_seconds: 30, max_retries: 2, }), }); const { data: job } = await response.json(); console.log(`Next run: ${job.next_execution_at}`);
body := strings.NewReader(`{ "name": "WordPress Cron Trigger", "url": "https://example.com/wp-cron.php", "method": "GET", "cron_expression": "*/5 * * * *", "timezone": "UTC", "timeout_seconds": 30, "max_retries": 2 }`) req, _ := http.NewRequest("POST", "https://watchcron.com/api/v1/cloud-crons", 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
{
"data": {
"uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "WordPress Cron Trigger",
"url": "https://example.com/wp-cron.php",
"method": "GET",
"status": "active",
"cron_expression": "*/5 * * * *",
"timezone": "UTC",
"timeout_seconds": 30,
"max_retries": 2,
"success_codes": null,
"success_keyword": null,
"prevent_overlap": false,
"is_running": false,
"is_active": true,
"consecutive_failures": 0,
"last_executed_at": null,
"next_execution_at": "2026-10-26T12:10:00Z",
"last_response_time_ms": null,
"last_status_code": null,
"last_error": null,
"maintenance_windows": null,
"created_at": "2026-10-26T12:06:00Z",
"updated_at": "2026-10-26T12:06:00Z"
}
}
Validation errors
If the request body is invalid, the API returns 422:
{
"error": "The url field is required."
}
Get a Cloud Cron job
/api/v1/cloud-crons/{uuid}
Returns full details for a single Cloud Cron job.
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/cloud-crons/c3d4e5f6-a7b8-9012-cdef-123456789012"
$uuid = 'c3d4e5f6-a7b8-9012-cdef-123456789012'; $response = Http::withToken('YOUR_API_KEY') ->get("https://watchcron.com/api/v1/cloud-crons/{$uuid}"); $job = $response->json('data');
uuid = "c3d4e5f6-a7b8-9012-cdef-123456789012" response = requests.get( f"https://watchcron.com/api/v1/cloud-crons/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) job = response.json()["data"]
const uuid = "c3d4e5f6-a7b8-9012-cdef-123456789012"; const response = await fetch( `https://watchcron.com/api/v1/cloud-crons/${uuid}`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: job } = await response.json();
Returns the same Cloud Cron object as shown in Cloud Cron object. Returns 404 if the UUID does not exist or belongs to a different project.
Update a Cloud Cron job
/api/v1/cloud-crons/{uuid}
Updates one or more fields on an existing Cloud Cron job. Only include the fields you want to change — all fields are optional.
Request body
| Field | Type | Description |
|---|---|---|
name | string | Job name (max 255 characters) |
url | string | Target URL (max 2048 characters) |
method | string | GET, POST, PUT, PATCH, DELETE, or HEAD |
headers | array|null | Custom HTTP headers (replaces existing headers) |
body | string|null | Request body |
http_auth_user | string|null | HTTP Basic Auth username |
http_auth_pass | string|null | HTTP Basic Auth password |
cron_expression | string | Cron expression (max 100 characters) |
timezone | string|null | IANA timezone |
timeout_seconds | integer | Request timeout, 1–300 seconds |
max_retries | integer | Retry attempts, 0–5 |
success_codes | array|null | Accepted HTTP status codes (send null to reset to any 2xx) |
success_keyword | string|null | Response body keyword match |
success_keyword_absent | boolean | Invert keyword matching |
prevent_overlap | boolean | Skip execution during active run |
maintenance_windows | array|null | Maintenance windows (replaces existing) |
curl -X PUT https://watchcron.com/api/v1/cloud-crons/c3d4e5f6-a7b8-9012-cdef-123456789012 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cron_expression": "*/10 * * * *", "timeout_seconds": 60, "max_retries": 3 }'
$response = Http::withToken('YOUR_API_KEY') ->put("https://watchcron.com/api/v1/cloud-crons/{$uuid}", [ 'cron_expression' => '*/10 * * * *', 'timeout_seconds' => 60, 'max_retries' => 3, ]);
response = requests.put( f"https://watchcron.com/api/v1/cloud-crons/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "cron_expression": "*/10 * * * *", "timeout_seconds": 60, "max_retries": 3, }, )
const response = await fetch(`https://watchcron.com/api/v1/cloud-crons/${uuid}`, { method: "PUT", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ cron_expression: "*/10 * * * *", timeout_seconds: 60, max_retries: 3, }), });
Returns 200 OK with the updated Cloud Cron object.
"headers": {"X-Custom": "value"} replaces all existing custom headers. Send "headers": null to clear them.Delete a Cloud Cron job
/api/v1/cloud-crons/{uuid}
Permanently deletes a Cloud Cron job and all its execution logs.
curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/cloud-crons/c3d4e5f6-a7b8-9012-cdef-123456789012"
$response = Http::withToken('YOUR_API_KEY') ->delete("https://watchcron.com/api/v1/cloud-crons/{$uuid}");
response = requests.delete( f"https://watchcron.com/api/v1/cloud-crons/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, )
const response = await fetch( `https://watchcron.com/api/v1/cloud-crons/${uuid}`, { method: "DELETE", headers: { "Authorization": "Bearer YOUR_API_KEY" }, } );
Returns 204 No Content on success. This action is irreversible.
Pause or unpause a Cloud Cron job
/api/v1/cloud-crons/{uuid}/pause
Pauses or unpauses a Cloud Cron job. Paused jobs will not execute on their schedule and will not trigger alerts.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
paused | boolean | Yes | true to pause, false to unpause |
curl -X PATCH https://watchcron.com/api/v1/cloud-crons/c3d4e5f6-a7b8-9012-cdef-123456789012/pause \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"paused": true}'
$response = Http::withToken('YOUR_API_KEY') ->patch("https://watchcron.com/api/v1/cloud-crons/{$uuid}/pause", [ 'paused' => true, ]);
response = requests.patch( f"https://watchcron.com/api/v1/cloud-crons/{uuid}/pause", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={"paused": True}, )
const response = await fetch( `https://watchcron.com/api/v1/cloud-crons/${uuid}/pause`, { method: "PATCH", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ paused: true }), } );
Returns 200 OK with the updated Cloud Cron object. The status field will change to paused when paused and back to active when unpaused.
List execution logs
/api/v1/cloud-crons/{uuid}/logs
Returns a paginated list of execution logs for a Cloud Cron job, ordered by most recent first.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
per_page | integer | 25 | Results per page |
page | integer | 1 | Page number |
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/cloud-crons/c3d4e5f6-a7b8-9012-cdef-123456789012/logs?per_page=10"
$response = Http::withToken('YOUR_API_KEY') ->get("https://watchcron.com/api/v1/cloud-crons/{$uuid}/logs", [ 'per_page' => 10, ]); $logs = $response->json('data');
response = requests.get( f"https://watchcron.com/api/v1/cloud-crons/{uuid}/logs", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"per_page": 10}, ) logs = response.json()["data"]
const response = await fetch( `https://watchcron.com/api/v1/cloud-crons/${uuid}/logs?per_page=10`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: logs } = await response.json();
Response 200 OK
{
"data": [
{
"status": "success",
"status_code": 200,
"response_time_ms": 245,
"error": null,
"response_body": "",
"attempt": 1,
"executed_at": "2026-10-26T12:05:00Z"
},
{
"status": "failed",
"status_code": 503,
"response_time_ms": 5012,
"error": "Service Unavailable",
"response_body": "Maintenance in progress",
"attempt": 3,
"executed_at": "2026-10-26T12:00:00Z"
}
],
"meta": {
"pagination": {
"total": 1440,
"per_page": 10,
"current_page": 1,
"last_page": 144
}
}
}
Log entry fields
| Field | Type | Description |
|---|---|---|
status | string | Execution result: success or failed |
status_code | integer|null | HTTP status code returned by the target URL (null if the request timed out or DNS failed) |
response_time_ms | integer | Total response time in milliseconds |
error | string|null | Error message if the execution failed |
response_body | string|null | Captured response body (truncated to 10 KB) |
attempt | integer | Attempt number (1 = first try, 2+ = retries) |
executed_at | string | ISO 8601 timestamp of the execution |