Skip to main content
Every function can be called with a plain POST to the server. The request body is the function’s input and the response body is its output, in the encoding its contract takes, with no envelope. No client library is needed.
The same call is FunctionsService.Invoke on the API. This page covers the common tasks. Invoke over HTTP lists every header, status and field.

Make a call

Send the input with the content type the function’s contract takes:
Any other content type answers 415. The input may be up to 64 MiB, and a larger one answers 413. A successful call answers 200 with the output in the same content type. These headers say what ran: When every host is busy, the call waits in the queue. A call over plain HTTP waits for up to the server’s INVOKE_DEADLINE, 5 minutes by default. A function’s max concurrency also caps how many of its calls run at once, and the rest wait. To set a deadline per call, use FunctionsService.Invoke with a Connect or gRPC timeout instead. The server caps it at INVOKE_MAX_DEADLINE.

Pin a version

Without a version, a call runs the function’s current version. Add ?version= to run a specific one:
The version must be ready. A version that is still building or that failed answers 400 with failed_precondition.

Retry safely

Add an Idempotency-Key header, up to 255 bytes, to make a call safe to retry. The first call with a key runs the function. A later call with the same key, within the server’s idempotency window (24 hours by default), runs nothing and answers with the first call’s result, with Alchemy-Replayed: true. If the first call is still running, the later one waits for it.
A synchronous call with a key needs a function logs bucket, where hosts keep the output to replay. Without one it answers 400 with failed_precondition. Two calls that race for the same key may see 409 with aborted. Retry it and it replays.

Set retries

A call whose function raises, crashes or times out, or that the platform cannot run, runs again up to the function’s retries, with a wait that grows five times longer after each failure. Alchemy-Retries sets a call’s own, from 0 to 10:
A call whose input breaks the contract never runs again. See Invocations for how retries fit in the deadline.

Queue an async call

Add Prefer: respond-async and the call returns at once with 202. Nothing waits for the function, and its output is dropped. Its status, error, attempts and logs are still recorded.
An async call may wait in the queue, retries included, for up to the server’s ASYNC_MAX_AGE, 24 hours by default. With an Idempotency-Key seen before, it returns the invocation that key queued, with "replayed": true, and queues nothing. To follow the invocation, GET the Location. It answers the invocation as JSON, the same message GetInvocation returns:

Handle errors

There are two kinds of failure, and they answer differently. The function ran and failed. The response carries the function’s error as JSON with 500, or 504 when it timed out. The Alchemy-* headers are still set.
kind is FUNCTION_ERROR_KIND_RAISED, FUNCTION_ERROR_KIND_CRASHED, FUNCTION_ERROR_KIND_TIMEOUT or FUNCTION_ERROR_KIND_OUTPUT_INVALID. An output that broke the contract also lists its violations. The call was refused or the platform failed. The response is a JSON body with a code and a message, under the HTTP status the Connect protocol gives that code. Input that breaks the contract answers 400 with each violation:

Authenticate

With authentication enabled, send a bearer token:
Behind a gateway with the proxy provider, the gateway sets the identity headers instead. Because the request must carry the contract’s content type, a browser on another site cannot invoke with a session cookie alone.