Trigger a manual run

POST

/api/v1/jobs/{jobDefinitionId}/runs

• Generated server url

Creates or replays one pending manual run after EXECUTE permission. The idempotency key is scoped to manual trigger requests and remains replay-safe within the server retention window. Protected mutations require the session cookie and CSRF header.

Authorizations

• csrfHeader
• sessionCookie

Parameters

Path Parameters

jobDefinitionId

required

string format: uuid

Job definition identifier.

Header Parameters

Idempotency-Key

required

string

<= 255 characters

Example

orders-sync-20260907-001

Required non-blank key for replay-safe manual triggering; maximum 255 characters.

Responses

202

Run accepted or an existing idempotent result replayed

Public durable run state and attempt lineage. Lease tokens and resolved datasource security are never exposed.

object

attempt

One-based attempt number.

integer format: int32

>= 1

availableAt

Earliest database time at which this attempt is eligible for claim.

string format: date-time

cancellationWarning

Mode-specific warning about sink state after cancellation.

string

nullable

committedWatermark

Incremental watermark committed only by successful finalization.

string

nullable

createdAt

Run creation timestamp in UTC.

string format: date-time

durationMillis

Elapsed execution time in milliseconds when reported.

integer format: int64

nullable

errorMessage

Credential-redacted failure detail.

string

nullable

executorIdentity

Worker identity assigned after claim.

string

nullable

finishedAt

Terminal completion timestamp in UTC.

string format: date-time

nullable

heartbeatAt

Most recent successful worker heartbeat in UTC.

string format: date-time

nullable

id

Run attempt identifier.

string format: uuid

jobDefinitionId

Owning job definition identifier.

string format: uuid

leaseUntil

Current claim expiry timestamp in UTC.

string format: date-time

nullable

previousRunId

Previous attempt in the retry chain.

string format: uuid

nullable

rowsProcessed

Rows processed by this attempt when reported.

integer format: int64

nullable

startedAt

Execution start timestamp in UTC.

string format: date-time

nullable

status

Durable lifecycle state.

string

Allowed values: PENDING RUNNING SUCCEEDED FAILED CANCEL_REQUESTED CANCELLED RETRY_SCHEDULED

400

The request is malformed or fails validation.

RFC 7807 problem response. Dynamic detail text is credential-redacted.

object

detail

string

instance

string format: uri-reference

status

integer format: int32

title

string

type

string format: uri-reference

401

Authentication is required or credentials are invalid.

RFC 7807 problem response. Dynamic detail text is credential-redacted.

object

detail

string

instance

string format: uri-reference

status

integer format: int32

title

string

type

string format: uri-reference

403

The authenticated identity lacks the required permission.

RFC 7807 problem response. Dynamic detail text is credential-redacted.

object

detail

string

instance

string format: uri-reference

status

integer format: int32

title

string

type

string format: uri-reference

404

The requested resource does not exist or is not visible.

RFC 7807 problem response. Dynamic detail text is credential-redacted.

object

detail

string

instance

string format: uri-reference

status

integer format: int32

title

string

type

string format: uri-reference

409

The request conflicts with the current resource or run state.

RFC 7807 problem response. Dynamic detail text is credential-redacted.

object

detail

string

instance

string format: uri-reference

status

integer format: int32

title

string

type

string format: uri-reference