API Reference

Report run completion

POST /api/executor-callbacks/runs/{id}/complete

Delivered by the executor (via its durable completion journal) when a task run finishes. Idempotent: a late duplicate for a run already terminal via a user stop or a prior completion is skipped. A run marked terminal by the run reaper (terminal_source='reaper') is overwritten — the executor's journaled truth wins over the reaper's guessed failed verdict.

Operation IDexecutorCompleteRun

Authentication

ExecutorKeyAuth·http bearer·Shared executor secret (ENVOY_EXECUTOR_KEY). Used by internal executor-to-control-plane routes (registration, heartbeat, completion/log callbacks).·Internal executor authentication; use the shared executor key.

Path parameters

idintegerrequired

Resource ID

Request body

This request body is required.

Content typeapplication/json

requestobject

4 properties

executionIdstringrequired

Executor-side execution correlation ID.

exitCodeinteger | nullrequired

Subprocess exit code. null indicates an abort without a numeric status.

Nullable: yes

completedAtstring · date-time

Optional ISO timestamp of when the task actually finished (journaled by the executor at exit). Preferred over the server's now so a late redelivery after control-plane downtime doesn't inflate duration_ms or stamp a wrong completed_at.

reasonstring

Optional completion reason. executor_shutdown marks an infra-initiated interruption (deploy/restart) and is recorded as a failure, not a user cancellation.

Allowed values: executor_shutdown

Success response body

200Completion recorded (or skipped as a duplicate).

Completion recorded (or skipped as a duplicate).

Content typeapplication/json

responseobject

2 properties

okboolean

skippedboolean

True when the run was already terminal from a user stop or prior completion and the duplicate was ignored.

Error responses

404Resource not found

Resource not found

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

{
  "error": "NOT_FOUND",
  "message": "Resource not found"
}

Code examples

curl --request POST \
  --url 'https://your-envoy.example.com/api/executor-callbacks/runs/YOUR_ID/complete' \
  --header 'Authorization: Bearer $EXECUTOR_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "executionId": "string",
  "exitCode": 0
}'

const response = await fetch("https://your-envoy.example.com/api/executor-callbacks/runs/YOUR_ID/complete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_EXECUTOR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "executionId": "string",
    "exitCode": 0
  }),
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = response.status === 204 ? null : await response.json();
console.log(data);