Execution
Execution is a single firing record for a scheduled job.
Execution records include:
status: EXECUTION_STATUS_COMPLETED, EXECUTION_STATUS_FAILED, or EXECUTION_STATUS_CANCELLED (cancellation, including operator or non-HTTP cancellation conditions).
endReason: Why a FAILED run failed, when the status alone does not say. "discarded" means the job exhausted maxAttempts and will not be retried. Empty otherwise.
httpStatus: HTTP status code returned by the target.
attempt: Attempt number (1-based) within this firing.
durationMs: End-to-end duration of the delivery attempt.
error: Error message on FAILED outcomes.
scheduledTime: When the execution was supposed to fire.
startedAt / completedAt: Actual start and completion times.
responseBody: Truncated HTTP response body captured on failed dispatches (4 KiB cap). Empty for successful dispatches.
responseHeaders: Allowlisted response headers from the failed dispatch: content-type, content-length, retry-after, x-request-id, date.
responseTruncated: true when responseBody was clipped at the 4 KiB cap.
responseSizeBytes: Original response size in bytes (from Content-Length when present, else total bytes read before truncation).
Usage profiles
| Usage | Fields and validation |
|---|---|
| In responses | View fields |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
executionId | string (int64) | Optional | Identifier of the scheduled job execution record. Pattern: ^-?\d+$. |
scheduleId | string | Optional | Identifier of the scheduled job. |
tenantId | string | Optional | Identifier of the tenant that owns or scopes this record. |
projectId | string | Optional | Identifier of the project within the tenant that scopes this record. |
scheduledTime | string (date-time) | Optional | Instant for which this execution or trigger was scheduled. |
startedAt | string (date-time) | Optional | Time at which the subscription or execution started. |
completedAt | string (date-time) | Optional | Time at which the scheduled execution completed. |
status | string (EXECUTION_STATUS_COMPLETED, EXECUTION_STATUS_FAILED, EXECUTION_STATUS_CANCELLED) or integer (int32) | Optional | Execution outcome recorded for this scheduled attempt. |
httpStatus | integer (int32) | Optional | HTTP status code returned by the target. Minimum: -2147483648. Maximum: 2147483647. |
attempt | integer (int32) | Optional | Attempt number (1-based). Minimum: -2147483648. Maximum: 2147483647. |
durationMs | integer (int32) | Optional | End-to-end duration in milliseconds. Minimum: -2147483648. Maximum: 2147483647. |
targetKind | string | Optional | Kind of target invoked by the scheduled execution. |
error | string | Optional | Error message when status is FAILED. |
riverJobId | string (int64) | Optional | Identifier of the underlying queue job that produced this scheduled execution, for correlating execution diagnostics. Pattern: ^-?\d+$. |
responseBody | string | Optional | Truncated HTTP response body captured on failed dispatches. Empty for successful dispatches by design — only error responses are stored. May also be empty for binary content types or transport-level errors (see response_size_bytes / error). |
responseHeaders | Map from string to string | Optional | Allowlisted response headers from the failed dispatch. Allowlist: content-type, content-length, retry-after, x-request-id, date. |
responseTruncated | boolean | Optional | True when response_body was clipped at the 4 KiB cap. |
responseSizeBytes | integer (int32) | Optional | Original response size in bytes (from Content-Length when present, else total bytes read before truncation). Minimum: -2147483648. Maximum: 2147483647. |
endReason | string | Optional | Explanation of an execution failure when status alone is insufficient, such as discarded after retry attempts were exhausted. Empty when there is no additional reason. |
Values of status
Terminal result of one scheduled-job firing; end_reason gives the reason for a non-successful result.
| Value | No. | Form | Meaning |
|---|---|---|---|
EXECUTION_STATUS_COMPLETED | 1 | Canonical | The scheduled HTTP dispatch received a status below 400; this does not establish completion of downstream asynchronous work. |
EXECUTION_STATUS_FAILED | 2 | Canonical | The firing failed, including exhausted delivery attempts; inspect end_reason. |
EXECUTION_STATUS_CANCELLED | 5 | Canonical | The firing was cancelled rather than completed, for example by an operator or a non-HTTP cancellation condition. |
Where used
| Reference | Relationship |
|---|---|
| List executions for a scheduled job | POST /api/v1/scheduler/list-executions |
Download the public reference contract.
Document: DOC-API-MODEL-execution.