Execution_

Appwrite Functions can be executed in several ways. Executions can be invoked through the Appwrite SDK and visiting its REST endpoint. Functions can also be triggered by events and scheduled executions. Here are all the different ways to consume your Appwrite Functions.

Execution modes

Appwrite Functions support two execution modes: synchronous and asynchronous.

Synchronous executions

Synchronous executions are those where Appwrite makes the request to the function runtime synchronously and waits for the response. The client making the request will wait until the function completes and receives the response directly.

Synchronous executions are created via:

• The Create execution endpoint where the async parameter is false
• Requests to custom or auto-generated domains

Synchronous executions:

• Return response bodies and headers directly to the client
• Have a 30-second hard timeout limit to discourage slow API calls that cause poor user experience in apps
• Are ideal for short-running operations where you need response data quickly

Asynchronous executions

Asynchronous executions are added to a queue and processed by the function worker as background jobs.

Asynchronous executions are created via:

• The Create execution endpoint where the async parameter is true
• Event triggers (when functions are triggered by platform events)
• Scheduled executions (intervals, cron jobs, or delayed executions)

Asynchronous executions:

• Have no timeout limitations beyond your function's configured timeout
• Are ideal for background processing and event-driven workflows

Domains

You can execute a function through HTTP requests, using a browser or by sending an HTTP request.

1. In the Appwrite Console's sidebar, click Functions.
2. Under Execute access, set the access to Any so that anyone can execute the function. You will use JWTs to authenticate users.
3. Under the Domains tab, you'll find the generated domain from Appwrite and your custom domains. Learn about adding a custom domain.

https://64d4d22db370ae41a32e.fra.appwrite.run

When requests are made to this domain, whether through a browser or through an HTTP request, the request information like request URL, request headers, and request body will be passed to the function.

curl -X POST https://64d4d22db370ae41a32e.fra.appwrite.run \
-H "X-Custom-Header: 123" \
-H "x-appwrite-user-jwt: <YOUR_JWT_KEY>" \
-H "Content-Type: application/json" \
-d '{"data":"this is json data"}'

Notice how a x-appwrite-user-jwt header is passed in the request, you will use this to authenticate users. Learn more about JWTs.

This unlocks the ability for you to develop custom HTTP endpoints with Appwrite Functions. It also allows accepting incoming webhooks for handling online payments, hosting social platform bots, and much more.

SDK

You can invoke your Appwrite Functions directly from the Appwrite SDKs.

import { Client, Functions } from "appwrite";

const client = new Client();

const functions = new Functions(client);

client
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<PROJECT_ID>') // Your project ID
;

const promise = functions.createExecution({
    functionId: '<FUNCTION_ID>',
    body: '<BODY>',  // optional
    async: false,  // optional
    xpath: '<PATH>',  // optional
    method: 'GET',  // optional
    headers: {} // optional
});

promise.then(function (response) {
    console.log(response); // Success
}, function (error) {
    console.log(error); // Failure
});

const sdk = require('node-appwrite');

// Init SDK
const client = new sdk.Client();

const functions = new sdk.Functions(client);

client
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<PROJECT_ID>') // Your project ID
;

const promise = functions.createExecution({
    functionId: '<FUNCTION_ID>',
    body: '<BODY>',  // optional
    async: false,  // optional
    xpath: '<PATH>',  // optional
    method: sdk.ExecutionMethod.GET,  // optional
    headers: {} // optional
});

promise.then(function (response) {
    console.log(response); // Success
}, function (error) {
    console.log(error); // Failure
});

Console

Another easy way to test a function is directly in the Appwrite Console. You test a function by hitting the Execute now button, which will display a modal below.

You'll be able to mock executions by configuring the path, method, headers, and body.

Events

Changes in Appwrite emit events. You can configure Functions to be executed in response to these events.

1. In Appwrite Console, navigate to Functions.
2. Click to open a function you wish to configure.
3. Under the Settings tab, navigate to Events.
4. Add one or multiple events as triggers for the function.
5. Be careful to avoid selecting events that can be caused by the function itself. This can cause the function to trigger its own execution, resulting in infinite recursions.

In these executions, the event that triggered the function will be passed as the header x-appwrite-event to the function. The request.body parameter will contain the event data. Learn more about events.

You can use one of the following events.

Schedule

Appwrite supports recurring function executions. Set a schedule in the Appwrite Console under your function's Settings > Executions, or with a Server SDK using either the interval parameter (minutes) or the schedule parameter (a cron expression). A function uses one or the other, not both.

Interval

An interval runs your function every N minutes. Think of it as cron where Appwrite picks the time for you: an hourly interval runs at the same point in every hour, such as 37 minutes and 21 seconds past, chosen for your function.

every 60 minutes  →  14:37:21, 15:37:21, 16:37:21, ...

Each function gets its own time within the interval, so functions with the same interval don't all start at the same moment.

The interval is a whole number of minutes, as low as 1. On Appwrite Cloud, the Free and Education plans support intervals of 60 minutes or longer.

Run times are fixed to the UTC clock, not counted from when you save the function:

• The first run can be up to one full interval away. A daily interval may first run almost 24 hours after you set it.
• A daily interval (1440 minutes) runs at one fixed UTC time of day, which you can't choose. Use cron if the time of day matters.
• An interval that isn't a factor or multiple of 60, such as 45 or 90 minutes, doesn't run at the same time every hour.
• Changing the interval can move the time Appwrite picks.

To set an interval in the Appwrite Console, open your function and go to Settings > Executions. In the Schedule card, choose Interval, pick a preset or choose Custom to enter a number of minutes, hours or days, and click Update.

With a Server SDK, pass interval when you create or update a function:

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<PROJECT_ID>') // Your project ID
    .setKey('<API_KEY>'); // Your secret API key

const functions = new sdk.Functions(client);

// Run the function every 6 hours
await functions.update({
    functionId: '<FUNCTION_ID>',
    name: '<NAME>', // name is required by update
    interval: 360
});

With the Appwrite CLI 28.3.0 or later, pass --interval:

appwrite functions update --function-id <FUNCTION_ID> --name <NAME> --interval 360

To keep an interval in appwrite.config.json, set "interval" on the function and run appwrite push functions.

Set interval to 0 to stop running on an interval. An update that leaves out interval keeps the current one, but an update that leaves out schedule clears the cron expression, so pass schedule again whenever you update a function that uses cron.

Cron

A cron expression, set with the schedule parameter, runs your function at the times it describes, as frequently as every minute. Use cron when the time of day matters. On the Appwrite Cloud Free and Education plans, cron runs can start up to 5 minutes after the scheduled time.

Here are some cron expressions for common schedules:

Setting a cron expression with the schedule parameter clears the function's interval.

Scheduled executions, from an interval or a cron expression, show schedule as their trigger in the execution logs.

Delayed executions

You can also delay function executions, which trigger the function only once at a future date and time. You can schedule a function execution using the Appwrite Console, a Client SDK, or a Server SDK.

ConsoleClient SDKServer SDK

To schedule an execution, navigate to Your function > Executions > Execute now > Schedule in the Appwrite Console.

Permissions

Appwrite Functions can be executed using Client or Server SDKs. Client SDKs must be authenticated with an account that has been granted execution permissions on the function's settings page. Server SDKs require an API key with the correct scopes.

If your function has a generated or custom domain, executions are not authenticated. Anyone visiting the configured domains will be considered a guest, so make sure to give Any execute permission in order for domain executions to work. If you need to enforce permissions for functions with a domain, use authentication methods like JWT.