1. docs
  2. api
  3. resources
  4. cron jobs
Start Monitoring

Cron Jobs

Create and manage cron job monitors. Record pings and get execution history.Last updated: 2026-02-14

Cron job monitors track scheduled tasks by receiving pings when jobs complete. If a ping is not received within the expected window, the job is marked as late and alerts are triggered.

GET /v1/cron-jobs

Returns all cron job monitors for your team.

Required Scope

cron-jobs:read

Example Request

cURL

curl https://api.uptime.example.com/v1/cron-jobs \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": [
		{
			"id": "cron_abc123",
			"name": "Daily Backup",
			"description": "Runs database backup every night",
			"cronExpression": "0 2 * * *",
			"gracePeriodSeconds": 300,
			"timezone": "America/New_York",
			"status": "healthy",
			"alertOnLate": true,
			"lastPingAt": "2026-02-14T07:00:12Z",
			"nextExpectedAt": "2026-02-15T07:00:00Z",
			"enabledAt": "2026-01-10T14:30:00Z",
			"createdAt": "2026-01-10T14:30:00Z",
			"updatedAt": "2026-02-01T09:15:00Z"
		}
	]
}

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have cron-jobs:read scope
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": {
			"type": "array",
			"items": { "$ref": "#/$defs/cronJob" }
		}
	},
	"$defs": {
		"cronJob": {
			"type": "object",
			"required": [
				"id",
				"name",
				"description",
				"cronExpression",
				"gracePeriodSeconds",
				"timezone",
				"status",
				"alertOnLate",
				"lastPingAt",
				"nextExpectedAt",
				"enabledAt",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": { "type": "string", "pattern": "^cron_[a-zA-Z0-9]+$" },
				"name": { "type": "string", "minLength": 1, "maxLength": 100 },
				"description": { "type": ["string", "null"], "maxLength": 500 },
				"cronExpression": { "type": "string" },
				"gracePeriodSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 },
				"timezone": { "type": "string" },
				"status": { "type": "string", "enum": ["healthy", "late", "missed", "new"] },
				"alertOnLate": { "type": "boolean" },
				"lastPingAt": { "type": ["string", "null"], "format": "date-time" },
				"nextExpectedAt": { "type": ["string", "null"], "format": "date-time" },
				"enabledAt": { "type": ["string", "null"], "format": "date-time" },
				"createdAt": { "type": "string", "format": "date-time" },
				"updatedAt": { "type": "string", "format": "date-time" }
			}
		}
	}
}

POST /v1/cron-jobs

Creates a new cron job monitor.

Required Scope

cron-jobs:write

Request Body

FieldTypeRequiredDescription
namestringYesDisplay name (1-100 characters)
cronExpressionstringYesValid cron expression (e.g., 0 * * * *)
descriptionstringNoOptional description (max 500 characters)
gracePeriodSecondsintegerNoSeconds to wait before marking late (60-86400, default 300)
timezonestringNoIANA timezone (default UTC)
alertOnLatebooleanNoSend alerts when job is late (default false)
enabledbooleanNoWhether the monitor is active (default true)

Example Request

cURL

curl -X POST https://api.uptime.example.com/v1/cron-jobs \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Backup",
    "cronExpression": "0 2 * * *",
    "description": "Runs database backup every night",
    "gracePeriodSeconds": 600,
    "timezone": "America/New_York",
    "alertOnLate": true
  }'

Response

{
	"data": {
		"id": "cron_abc123",
		"name": "Daily Backup",
		"description": "Runs database backup every night",
		"cronExpression": "0 2 * * *",
		"gracePeriodSeconds": 600,
		"timezone": "America/New_York",
		"status": "unknown",
		"alertOnLate": true,
		"lastPingAt": null,
		"nextExpectedAt": "2026-02-15T07:00:00Z",
		"enabledAt": "2026-02-14T15:30:00Z",
		"createdAt": "2026-02-14T15:30:00Z",
		"updatedAt": "2026-02-14T15:30:00Z"
	}
}

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid request body or cron expression
400LIMIT_EXCEEDEDMaximum number of cron jobs reached
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have cron-jobs:write scope
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Request Body Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["name", "cronExpression"],
	"properties": {
		"name": { "type": "string", "minLength": 1, "maxLength": 100 },
		"cronExpression": { "type": "string" },
		"description": { "type": "string", "maxLength": 500 },
		"gracePeriodSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 300 },
		"timezone": { "type": "string", "default": "UTC" },
		"alertOnLate": { "type": "boolean", "default": false },
		"enabled": { "type": "boolean", "default": true }
	}
}

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": { "$ref": "#/$defs/cronJob" }
	},
	"$defs": {
		"cronJob": {
			"type": "object",
			"required": [
				"id",
				"name",
				"description",
				"cronExpression",
				"gracePeriodSeconds",
				"timezone",
				"status",
				"alertOnLate",
				"lastPingAt",
				"nextExpectedAt",
				"enabledAt",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": { "type": "string", "pattern": "^cron_[a-zA-Z0-9]+$" },
				"name": { "type": "string", "minLength": 1, "maxLength": 100 },
				"description": { "type": ["string", "null"], "maxLength": 500 },
				"cronExpression": { "type": "string" },
				"gracePeriodSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 },
				"timezone": { "type": "string" },
				"status": { "type": "string", "enum": ["healthy", "late", "missed", "new"] },
				"alertOnLate": { "type": "boolean" },
				"lastPingAt": { "type": ["string", "null"], "format": "date-time" },
				"nextExpectedAt": { "type": ["string", "null"], "format": "date-time" },
				"enabledAt": { "type": ["string", "null"], "format": "date-time" },
				"createdAt": { "type": "string", "format": "date-time" },
				"updatedAt": { "type": "string", "format": "date-time" }
			}
		}
	}
}

GET /v1/cron-jobs/:id

Returns a single cron job monitor by ID.

Required Scope

cron-jobs:read

Example Request

cURL

curl https://api.uptime.example.com/v1/cron-jobs/cron_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": {
		"id": "cron_abc123",
		"name": "Daily Backup",
		"description": "Runs database backup every night",
		"cronExpression": "0 2 * * *",
		"gracePeriodSeconds": 600,
		"timezone": "America/New_York",
		"status": "healthy",
		"alertOnLate": true,
		"lastPingAt": "2026-02-14T07:00:12Z",
		"nextExpectedAt": "2026-02-15T07:00:00Z",
		"enabledAt": "2026-01-10T14:30:00Z",
		"createdAt": "2026-01-10T14:30:00Z",
		"updatedAt": "2026-02-01T09:15:00Z"
	}
}

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have cron-jobs:read scope
404NOT_FOUNDCron job not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": { "$ref": "#/$defs/cronJob" }
	},
	"$defs": {
		"cronJob": {
			"type": "object",
			"required": [
				"id",
				"name",
				"description",
				"cronExpression",
				"gracePeriodSeconds",
				"timezone",
				"status",
				"alertOnLate",
				"lastPingAt",
				"nextExpectedAt",
				"enabledAt",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": { "type": "string", "pattern": "^cron_[a-zA-Z0-9]+$" },
				"name": { "type": "string", "minLength": 1, "maxLength": 100 },
				"description": { "type": ["string", "null"], "maxLength": 500 },
				"cronExpression": { "type": "string" },
				"gracePeriodSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 },
				"timezone": { "type": "string" },
				"status": { "type": "string", "enum": ["healthy", "late", "missed", "new"] },
				"alertOnLate": { "type": "boolean" },
				"lastPingAt": { "type": ["string", "null"], "format": "date-time" },
				"nextExpectedAt": { "type": ["string", "null"], "format": "date-time" },
				"enabledAt": { "type": ["string", "null"], "format": "date-time" },
				"createdAt": { "type": "string", "format": "date-time" },
				"updatedAt": { "type": "string", "format": "date-time" }
			}
		}
	}
}

PUT /v1/cron-jobs/:id

Updates an existing cron job monitor.

Required Scope

cron-jobs:write

Request Body

All fields are optional. Only provided fields will be updated.

FieldTypeDescription
namestringDisplay name (1-100 characters)
cronExpressionstringValid cron expression
descriptionstringOptional description (max 500 characters)
gracePeriodSecondsintegerSeconds to wait before marking late (60-86400)
timezonestringIANA timezone
alertOnLatebooleanSend alerts when job is late
enabledbooleanWhether the monitor is active

Example Request

cURL

curl -X PUT https://api.uptime.example.com/v1/cron-jobs/cron_abc123 \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodSeconds": 900,
    "alertOnLate": false
  }'

Response

{
	"data": {
		"id": "cron_abc123",
		"name": "Daily Backup",
		"description": "Runs database backup every night",
		"cronExpression": "0 2 * * *",
		"gracePeriodSeconds": 900,
		"timezone": "America/New_York",
		"status": "healthy",
		"alertOnLate": false,
		"lastPingAt": "2026-02-14T07:00:12Z",
		"nextExpectedAt": "2026-02-15T07:00:00Z",
		"enabledAt": "2026-01-10T14:30:00Z",
		"createdAt": "2026-01-10T14:30:00Z",
		"updatedAt": "2026-02-14T16:45:00Z"
	}
}

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid request body or cron expression
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have cron-jobs:write scope
404NOT_FOUNDCron job not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Request Body Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"name": { "type": "string", "minLength": 1, "maxLength": 100 },
		"cronExpression": { "type": "string" },
		"description": { "type": "string", "maxLength": 500 },
		"gracePeriodSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 },
		"timezone": { "type": "string" },
		"alertOnLate": { "type": "boolean" },
		"enabled": { "type": "boolean" }
	}
}

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": { "$ref": "#/$defs/cronJob" }
	},
	"$defs": {
		"cronJob": {
			"type": "object",
			"required": [
				"id",
				"name",
				"description",
				"cronExpression",
				"gracePeriodSeconds",
				"timezone",
				"status",
				"alertOnLate",
				"lastPingAt",
				"nextExpectedAt",
				"enabledAt",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": { "type": "string", "pattern": "^cron_[a-zA-Z0-9]+$" },
				"name": { "type": "string", "minLength": 1, "maxLength": 100 },
				"description": { "type": ["string", "null"], "maxLength": 500 },
				"cronExpression": { "type": "string" },
				"gracePeriodSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 },
				"timezone": { "type": "string" },
				"status": { "type": "string", "enum": ["healthy", "late", "missed", "new"] },
				"alertOnLate": { "type": "boolean" },
				"lastPingAt": { "type": ["string", "null"], "format": "date-time" },
				"nextExpectedAt": { "type": ["string", "null"], "format": "date-time" },
				"enabledAt": { "type": ["string", "null"], "format": "date-time" },
				"createdAt": { "type": "string", "format": "date-time" },
				"updatedAt": { "type": "string", "format": "date-time" }
			}
		}
	}
}

DELETE /v1/cron-jobs/:id

Deletes a cron job monitor. This action cannot be undone.

Required Scope

cron-jobs:write

Example Request

cURL

curl -X DELETE https://api.uptime.example.com/v1/cron-jobs/cron_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"

Response

Returns 204 No Content on success with an empty response body.

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have cron-jobs:write scope
404NOT_FOUNDCron job not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

Returns 204 No Content with an empty response body on success.

GET /v1/cron-jobs/:id/ping

Returns the ping history for a cron job monitor.

Required Scope

cron-jobs:read

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoNumber of results (1-100, default 20)
offsetintegerNoPagination offset (default 0)

Example Request

cURL

curl "https://api.uptime.example.com/v1/cron-jobs/cron_abc123/ping?limit=10&offset=0" \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": [
		{
			"id": "ping_xyz789",
			"cronJobId": "cron_abc123",
			"receivedAt": "2026-02-14T07:00:12Z",
			"status": "on_time"
		},
		{
			"id": "ping_xyz788",
			"cronJobId": "cron_abc123",
			"receivedAt": "2026-02-13T07:00:08Z",
			"status": "on_time"
		},
		{
			"id": "ping_xyz787",
			"cronJobId": "cron_abc123",
			"receivedAt": "2026-02-12T07:10:45Z",
			"status": "late"
		}
	],
	"pagination": {
		"total": 45,
		"limit": 10,
		"offset": 0
	}
}

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid query parameters
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have cron-jobs:read scope
404NOT_FOUNDCron job not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data", "pagination"],
	"properties": {
		"data": {
			"type": "array",
			"items": { "$ref": "#/$defs/ping" }
		},
		"pagination": {
			"type": "object",
			"required": ["total", "limit", "offset"],
			"properties": {
				"total": { "type": "integer", "minimum": 0 },
				"limit": { "type": "integer", "minimum": 1, "maximum": 100 },
				"offset": { "type": "integer", "minimum": 0 }
			}
		}
	},
	"$defs": {
		"ping": {
			"type": "object",
			"required": ["id", "cronJobId", "receivedAt", "status"],
			"properties": {
				"id": { "type": "string", "pattern": "^ping_[a-zA-Z0-9]+$" },
				"cronJobId": { "type": "string", "pattern": "^cron_[a-zA-Z0-9]+$" },
				"receivedAt": { "type": "string", "format": "date-time" },
				"status": { "type": "string", "enum": ["on_time", "late"] }
			}
		}
	}
}

POST /v1/cron-jobs/:id/ping

Records a ping for a cron job monitor. Call this endpoint when your scheduled task completes successfully.

Rate Limit: This endpoint is rate limited to 1 request per minute per cron job. Additional requests within the same minute will be rejected with a 429 error.

Required Scope

cron-jobs:ping

Example Request

cURL

curl -X POST https://api.uptime.example.com/v1/cron-jobs/cron_abc123/ping \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": {
		"id": "ping_xyz790",
		"cronJobId": "cron_abc123",
		"receivedAt": "2026-02-14T07:00:12Z",
		"status": "on_time"
	}
}

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have cron-jobs:ping scope
404NOT_FOUNDCron job not found
409CONFLICTCron job is disabled
429RATE_LIMITEDMore than 1 ping per minute for this job
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": { "$ref": "#/$defs/ping" }
	},
	"$defs": {
		"ping": {
			"type": "object",
			"required": ["id", "cronJobId", "receivedAt", "status"],
			"properties": {
				"id": { "type": "string", "pattern": "^ping_[a-zA-Z0-9]+$" },
				"cronJobId": { "type": "string", "pattern": "^cron_[a-zA-Z0-9]+$" },
				"receivedAt": { "type": "string", "format": "date-time" },
				"status": { "type": "string", "enum": ["on_time", "late"] }
			}
		}
	}
}

Response Fields

All cron job responses include these fields:

FieldTypeDescription
idstringUnique identifier (prefixed with cron_)
namestringDisplay name
descriptionstring | nullOptional description
cronExpressionstringCron schedule expression
gracePeriodSecondsintegerSeconds to wait before marking late
timezonestringIANA timezone for the schedule
statusstringCurrent status: healthy, late, or unknown
alertOnLatebooleanWhether alerts are sent when the job is late
lastPingAtstring | nullISO 8601 timestamp of the last ping, or null if never
nextExpectedAtstring | nullISO 8601 timestamp of the next expected ping
enabledAtstring | nullISO 8601 timestamp when enabled, or null if disabled
createdAtstringISO 8601 timestamp when created
updatedAtstringISO 8601 timestamp when last updated