Sign in
Durable Functions

Start a durable execution

Changed on

Starts an execution and returns its handle. Never returns a result: an execution can outlive any request a client could hold open, so the result is read back from GET /projects/{id}/durable-functions/{functionId}/executions/{executionId}.

The request body is the execution's input and must be valid JSON if present. An empty body starts the execution with no input.

Send X-Volcano-Execution-Name to make the start idempotent: repeating a start with the same name returns the existing execution instead of beginning a second one.

Each execution counts against the project's durable execution allowance, the operations it performs count against the durable operations allowance when it finishes, and the number of executions in flight at once is capped by the plan.

post/projects/{id}/durable-functions/{functionId}/executions

Request

  • Base URL: https://api.volcano.dev
  • URL: https://api.volcano.dev/projects/{id}/durable-functions/{functionId}/executions
  • Auth: HTTP bearer

Path parameters

idstring uuid required

Project ID

functionIdstring required

Durable function ID, or its name within the project

Headers

X-Volcano-Execution-Namestring

Idempotency key for this execution. Generated when omitted. A repeat under a name that already names a running execution returns that execution and is not charged again.

Letters, digits, -, _ and ., up to 255 characters. Anything else is rejected with 400.

Request body

unknown required

Response

Execution accepted and started

idstring uuid required
function_idstring uuid required
namestring required

Idempotency key for the execution. Supplied by the client through X-Volcano-Execution-Name, otherwise generated.

status'pending' | 'running' | 'succeeded' | 'failed' | 'timed_out' | 'stopped' | 'unknown' required

Lifecycle state of an execution. pending covers the window between the platform reserving the execution name and the function accepting the start, and has no counterpart once the execution is under way. succeeded, failed, timed_out, stopped and unknown are terminal.

unknown means the execution's outcome cannot be established, so no result or error can be given for it. Either it was under way and was never seen to finish, or its start failed with a 500 without the platform establishing whether the execution began — which is why a name whose start returned an error can later read as unknown rather than not being found. It is terminal because nothing can settle it later, and it is rare — treat it as an outcome to retry rather than a state to wait on. A retry under the same name picks this execution back up instead of starting a second one, and needs a free concurrency slot because an unknown execution has given its own up. completed_at on an unknown execution is when the platform gave up, not when the work ended.

regionstring required

Region the execution runs in. An execution is pinned to one region for its whole life because its checkpoints live there.

resultunknown
result_expiredboolean

true when the execution is terminal but its result is no longer retained, which distinguishes a discarded result from an empty one. Shortly after that the execution itself is dropped and reads answer 404.

A result that was checkpointed rather than returned leaves this unset, so it reads like a function that returned nothing.

created_atstring date-time required
completed_atstring date-time

Present once the execution has reached a terminal status.

Changes