Executions

An execution is one recorded run of a job. The scheduler writes an execution when a job is queued (scheduled) and updates it when the executor reports back (success or failed).

Execution object

{
  "id": 123,
  "accountId": 123,
  "uniqueId": "a1b2c3d4e5f6...",
  "state": 1,
  "nodeId": 42,
  "jobId": 789,
  "lastExecutionDatetime": "2026-01-15T10:00:00Z",
  "nextExecutionDatetime": "2026-01-15T12:00:00Z",
  "jobQueueVersion": 5,
  "executionVersion": 2,
  "dateCreated": "2026-01-15T10:00:01Z",
  "dateModified": "2026-01-15T10:00:02Z"
}

Field	Description
state	Integer: 0 scheduled, 1 success, 2 failed
uniqueId	SHA-256 of projectId-jobId-lastExecutionDate-nextExecutionTime. Acts as an idempotency key so the same run is never processed twice across restarts or leader changes.
nodeId	Cluster node that handled the run
lastExecutionDatetime	When this run started
nextExecutionDatetime	The run's planned time (the job's next fire time when it was queued)
executionVersion	Increments each time the job is rescheduled after a success or after exhausting retries
jobQueueVersion	Internal queue version at the time of the run

Endpoints

Method	Path	Scope	Notes
GET	/executions	read	Filterable list
GET	/executions/analytics	read	Hourly counts around a point in time
GET	/executions/totals	read	Lifetime counts per state
POST	/executions/cleanup-old-logs	execute	Delete logs older than N months

List executions

curl "https://api.scheduler0.com/api/v1/executions?jobId=789&state=failed&limit=50&offset=0" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID"

Parameter	Description
startDate, endDate	RFC3339 bounds on the run time
projectId, jobId	Filters
state	scheduled, success or failed; any other value returns 400. Note the filter is a word while the response field is an integer.
orderBy	dateCreated, lastExecutionDateTime or nextExecutionDateTime
orderDirection	ASC or DESC
limit	Default 50 (no maximum)
offset	Default 0

Response: { "total", "offset", "limit", "executions": [...] }.

Parameter names differ from the other list endpoints (orderDirection rather than orderByDirection, camelCase orderBy values).

Analytics

GET /executions/analytics returns execution counts in hourly buckets for a 12-hour window centred on the point you pass: six hours before startDate startTime to six hours after. Both parameters are required and interpreted in UTC.

curl "https://api.scheduler0.com/api/v1/executions/analytics?startDate=2026-01-01&startTime=12:00:00" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID"

Parameter	Format
startDate	YYYY-MM-DD
startTime	HH:MM or HH:MM:SS

{
  "success": true,
  "data": {
    "accountId": 123,
    "timezone": "UTC",
    "startDate": "2026-01-01",
    "startTime": "06:00:00",
    "endDate": "2026-01-01",
    "endTime": "18:00:00",
    "points": [
      { "date": "2026-01-01", "time": "06:00:00", "scheduled": 10, "success": 8, "failed": 2 }
    ]
  }
}

Totals

curl "https://api.scheduler0.com/api/v1/executions/totals" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID"

{
  "success": true,
  "data": { "accountId": 123, "scheduled": 1000, "success": 950, "failed": 50 }
}

Delete old execution logs

POST /executions/cleanup-old-logs deletes this account's execution logs older than retentionMonths months. accountId is a string and must equal the X-Account-ID header; retentionMonths must be greater than 0. Requires the execute scope.

curl -X POST "https://api.scheduler0.com/api/v1/executions/cleanup-old-logs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -d '{"accountId": "123", "retentionMonths": 6}'

{ "success": true, "data": { "message": "..." } }

Related

• Jobs — retryMax and how a run becomes failed
• Account Management — monthly execution quota (self-hosted)