Sign in
Durable Functions

Start a durable execution from an application

Changed on

Starts an execution of a durable function using an application credential, and returns its handle.

This is the durable counterpart of POST /functions/{functionId}/invoke, and it is the endpoint an application calls. Like that one, it is not project-scoped: an anon key, a service key and an auth user token each carry their own project. The project-scoped collection under /projects/{id}/durable-functions/... remains the owner's management surface.

With a service key: any durable function in the project.

With an auth user token: a durable function whose visibility is authenticated or public.

With an anon key: requires the functions.invoke permission, and the function must have visibility: public.

A private durable function answers every credential but a service key exactly as a missing one, with 404.

Starting is all this endpoint does. Reading a result or stopping an execution requires the project owner's token, because an anon key is shared by everyone who loads the page and an execution is addressed by id alone.

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 once against the project's durable execution allowance, however many times the start is retried under the same execution name, and the number in flight at once is capped by the plan. The operations the execution performs are counted against the durable operations allowance when it finishes.

post/durable-functions/{functionId}/executions

Request

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

Path parameters

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