Skip to main content
An invocation is one call of one function version against one input. These RPCs are on functions.v1.FunctionsService, with messages in protos/functions/v1/invocations.proto. See Invocations for the lifecycle, and HTTP endpoints for the same calls over plain HTTP.

RPCs

Invoke

The input is checked against the version’s contract before anything runs and the output after the function writes it. The call waits in the queue while every host is busy or the function is at its max_concurrency, until the call’s deadline: Connect-Timeout-Ms when set, capped at INVOKE_MAX_DEADLINE (default 1 hour), or INVOKE_DEADLINE (default 5 minutes). An RPC error means the function produced no result. If the function ran, the RPC succeeds and the response carries its output or a FunctionError. FunctionError has a kind, a message, a function-supplied type (for RAISED only) and violations (for OUTPUT_INVALID only). StartKind is COLD_BOOT, SNAPSHOT_RESTORE or WARM.

Retries

An attempt that raised, crashed or timed out, or that the platform could not run, runs again up to the call’s or the function’s retries, while the deadline leaves room. The wait starts at RETRY_BACKOFF (default 1s), grows five times per attempt and stops growing at RETRY_BACKOFF_MAX (default 5m). An input that violates the contract never runs again.

Idempotency

Within IDEMPOTENCY_WINDOW (default 24h), a call to the same function with the same key returns the invocation the first call started, with its output or error, and replayed set. A call still in flight is waited on. The key is released for a new run only when the platform never sent the invocation to a host. A call a host took but never reported on holds the key, and a retry gets aborted. Use a new key to run again. Keys on Invoke need a logs bucket (LOGS_BUCKET) to keep outputs in, or the call is failed_precondition.

Errors

A host can also refuse an invocation with resource_exhausted, invalid_argument, unavailable, not_found, failed_precondition or aborted, which the server passes through.

InvokeAsync

Takes the same fields as Invoke. Returns once the invocation is queued, with invocation_id and replayed. Nothing waits for it and its output is dropped. Its status, attempts, error and logs are recorded. It retries as Invoke does and may wait in the queue and between attempts for up to ASYNC_MAX_AGE (default 24h), after which the host that takes it records it CANCELED. An idempotency_key seen within the window returns the invocation that call queued, with replayed set. Async keys do not need a logs bucket. Follow the invocation with GetInvocation.

GetInvocation

Takes id. Returns the Invocation from the database, or from the server holding it while it runs and until its record is written. An unknown id is not_found.

ListInvocations

Results are newest first. An invocation appears once its record reaches the database, after it ends or, for async invocations, once it is queued.

GetInvocationLogs

A server-streaming RPC that sends what the function wrote to stderr as data chunks, in order. Chunks are not split on line boundaries. An ended attempt is read from the logs bucket. A running one, or one whose upload has not completed, is read from NATS, which keeps only recent lines for LOGS_RETENTION (default 1h). An attempt below 0 or past the invocation’s attempts is not_found. See Logs.

TailInvocations

A server-streaming RPC of lifecycle transitions across every server, until the client goes away. Each TailInvocationsResponse carries the invocation, an event_type (the status as a lowercase token such as running or succeeded), replay and emitted_at in epoch milliseconds. A slow client that falls 256 events behind loses events rather than holding up invocations. Reconnect with should_replay to catch up. If the servers cannot be asked for replay, the call is unavailable.