Operation details
Page through jobs across the customer control plane
- operationId
listPlatformJobs- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.read_all platform.admin
Description (from the contract)
Requires a platform-scoped identity with jobs.read_all or platform.admin. tenant_id narrows the global query. The time window is left-closed and right-open and may not exceed 31 days. Explicit page selects numbered pagination with an exact scoped and filtered total; omit page to preserve the authenticated keyset cursor contract.
Parameters
listPlatformJobs Parameters| Name | In | Type | Required | Description |
|---|
from | query | string(date-time) | Yes | Inclusive RFC3339 creation-time bound. |
|---|
to | query | string(date-time) | Yes | Exclusive RFC3339 creation-time bound; from-to may not exceed 31 days. |
|---|
tenant_id | query | string(uuid) | No | Platform route only. Omit to query all tenants. |
|---|
task_id | query | string(uuid) | No | Exact task UUID filter. |
|---|
status | query | array<string: queued / running / succeeded / partial_failed / failed / cancelled> | No | Comma-separated job states; duplicates are rejected. |
|---|
kind | query | string | No | — |
|---|
resource | query | string | No | Exact match against the canonical job subject/reference, or a case-insensitive match against a node UUID assigned to one of the job's items, so node pages can deep-link to the tasks executed on that node. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
page | query | integer | No | Explicit canonical positive decimal page number, mutually exclusive with cursor even if cursor is empty. Count and rows use one read-only repeatable-read snapshot. Different requests are live snapshots and may move rows as jobs are inserted or change state. A page beyond the end returns an empty data array, the requested number and the exact total. |
|---|
Responses
listPlatformJobs Responses| Status | Description |
|---|
200 | Authenticated keyset page or explicit numbered page with a same-snapshot exact total. Fields：data: array<Job> page: Page | NumberedPage query: QueryWindow task_metadata?: array<TaskMetadata> |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Read the integrated producer kind catalog independently of job rows
- operationId
listPlatformJobKinds- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.read_all platform.admin
Description (from the contract)
Requires jobs.read_all or platform.admin. Accepts no query parameters. Integration means a production source path creates canonical job facts, not that its producer or worker is enabled or ready in this runtime.
Responses
listPlatformJobKinds Responses| Status | Description |
|---|
200 | Registered source-backed producer kinds, independent of current job rows or runtime enablement. Fields：data: array<JobKind> |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
↑ Back to list
Read a job visible to the platform administrator
- operationId
getPlatformJob- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.read_all platform.admin
Parameters
getPlatformJob Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
Responses
getPlatformJob Responses| Status | Description |
|---|
200 | Job projection without producer payload or credentials. Fields：data: Job |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Page through a job's immutable attempt history
- operationId
listPlatformJobAttempts- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.read_all platform.admin
Parameters
listPlatformJobAttempts Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listPlatformJobAttempts Responses| Status | Description |
|---|
200 | Attempt history ordered by attempt number descending. Fields：data: array<Attempt> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Cancel a queued or running job
- operationId
cancelPlatformJob- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.manage_all platform.admin
Description (from the contract)
Requires jobs.manage_all or platform.admin. The state transition, audit, and command receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
Parameters
cancelPlatformJob Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | Strong ETag value returned by the latest job detail or command response. |
|---|
Request body
application/json · Required：Yes
Responses
cancelPlatformJob Responses| Status | Description |
|---|
200 | Immutable cancelled or queued command result snapshot. Fields：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Page through append-only terminal-attempt dead letters
- operationId
listPlatformJobDeadLetters- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.read_all platform.admin
Parameters
listPlatformJobDeadLetters Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listPlatformJobDeadLetters Responses| Status | Description |
|---|
200 | Dead letters ordered by terminal attempt descending. Fields：data: array<DeadLetter> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Page through immutable per-attempt settlement receipts
- operationId
listPlatformJobSettlementReceipts- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.read_all platform.admin
Parameters
listPlatformJobSettlementReceipts Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listPlatformJobSettlementReceipts Responses| Status | Description |
|---|
200 | Settlement receipts ordered by attempt descending then ordinal ascending. Fields：data: array<SettlementReceipt> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Add one attempt and replay the latest dead-lettered job
- operationId
replayPlatformDeadLetteredJob- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.manage_all platform.admin
Description (from the contract)
Requires jobs.manage_all or platform.admin. The state transition, audit, replay fact, and command receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
Parameters
replayPlatformDeadLetteredJob Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | Strong ETag value returned by the latest job detail or command response. |
|---|
Request body
application/json · Required：Yes
Responses
replayPlatformDeadLetteredJob Responses| Status | Description |
|---|
200 | Immutable cancelled or queued command result snapshot. Fields：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Page through current per-item and per-node result projections
- operationId
listPlatformJobResults- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.read_all platform.admin
Parameters
listPlatformJobResults Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque, authenticated, versioned HMAC-SHA256 keyset cursor from the preceding response, bound to route scope, endpoint, task, and filters. Reuse with changed inputs or any token modification returns 400. |
|---|
Responses
listPlatformJobResults Responses| Status | Description |
|---|
200 | Current item projections ordered by immutable ordinal ascending. Fields：data: array<ItemResult> page: Page |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
Retry failed items in a failed or partially failed job
- operationId
retryPlatformJob- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：jobs.manage_all platform.admin
Description (from the contract)
Requires jobs.manage_all or platform.admin and an available attempt. The state transition, audit, and command receipt commit atomically. The same actor and Idempotency-Key return the immutable first successful snapshot with replayed=true; reuse for another command returns 409.
Parameters
retryPlatformJob Parameters| Name | In | Type | Required | Description |
|---|
task_id | path | string(uuid) | Yes | Canonical lower-case UUID of the background job. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | Strong ETag value returned by the latest job detail or command response. |
|---|
Request body
application/json · Required：Yes
Responses
retryPlatformJob Responses| Status | Description |
|---|
200 | Immutable cancelled or queued command result snapshot. Fields：data: Job replayed: boolean |
|---|
400 | job_invalid_request: invalid UUID, query input, Idempotency-Key, content type, or exact empty JSON command body. |
|---|
401 | job_authentication_required: authentication is missing or invalid. |
|---|
403 | job_permission_denied or job_scope_forbidden: permission is missing, audience is incompatible, or the caller attempted a scope override. |
|---|
404 | job_not_found: the task does not exist or is outside the authenticated tenant scope. |
|---|
408 | job_request_cancelled: the inbound request context was cancelled. |
|---|
409 | job_idempotency_conflict, job_invalid_transition, job_retries_exhausted, or job_producer_command_required: the key was reused for another command, the job changed or is ineligible, no retry attempt remains, or the job's producer owns the command. cache.operation cancel/retry is executed by the cache module (same audit and receipt as the cache operation API); job_producer_command_required is returned only for its replay, or when cache control is not enabled. |
|---|
412 | job_revision_conflict: the If-Match revision is stale; refresh the job before retrying. |
|---|
502 | job_store_invalid_response or job_response_too_large: stored facts were invalid or the bounded response was too large. |
|---|
503 | job_store_unavailable: PostgreSQL or the configured Reader is unavailable. |
|---|
504 | job_query_timeout: the bounded request timed out. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list