Sleep

Pause a task for minutes, hours, days, or weeks

The sleep API takes in a duration as a millisecond formatted string and returns a promise that resolves when the sleep finishes.

These are examples of valid sleep durations:

Syntax	Description
`"3000ms"`	3000 milliseconds
`"30s"`	30 seconds
`"10m"`	10 minutes
`"1h"`	1 hour
`"2d"`	2 days

The sleep duration cannot exceed the length of the task's timeout. Tasks with the standard runtime have a maximum exeuction time of 12 hours, while tasks with the workflow runtime can run up to 60 days. Tasks with the standard runtime will actively run until the promise resolves, but the workflow runtime can stop running entirely and continue when the sleep ends. See runtimes to choose which runtime is best suited for your use case.

Examples

Drip email campaign

With the sleep API and workflow runtime, you can create a drip email campaign. The following example sends an email immediately and then waits a week before sending the second email in the drip campaign.

typescript
Copied
1
import airplane from "airplane";
2

3
export default airplane.task(
4
  {
5
    slug: "email_campaign",
6
    parameters: {
7
      email: { name: "email", slug: "email", type: "shorttext" },
8
      name: { name: "name", slug: "name", type: "shorttext" },
9
    },
10
    runtime: "workflow",
11
  },
12
  async (params) => {
13
    await send_email({
14
      email: params.email,
15
      name: params.name,
16
      subject: "Welcome to Airplane!",
17
      message: `Hello, ${params.name}! To get started with Airplane, visit the docs: https://docs.airplane.dev`,
18
    });
19

20
    // Sleep for 7 days before sending the next email
21
    await airplane.sleep("7d");
22

23
    await send_email({
24
      email: params.email,
25
      name: params.name,
26
      subject: "Getting started with Airplane",
27
      message: `Hello, ${params.name}! Check out our [templates gallery](https://docs.airplane.dev/templates) for common use cases. As you give things a try, let us know if you have any feedback.`,
28
    });
29
  }
30
);
31

32
export const send_email = async (params: {
33
  email: string;
34
  name: string;
35
  subject: string;
36
  message: string;
37
}): Promise<number> => {
38
  const run = await airplane.email.message(
39
    "my_email",
40
    { email: "example@airplane.dev", name: "Airplane" },
41
    [{ email: params.email, name: params.name }],
42
    {
43
      subject: params.subject,
44
      message: params.message,
45
    }
46
  );
47
  return run.output.number_of_recipients;
48
};

Custom timeouts

You can use sleep to apply timeouts to operations, such as executing tasks or prompting operators. This example creates a background prompt that waits for an operator to respond. Normally, this task would wait for the prompt until the run times out, but the sleep API can be used to enforce a shorter timeout.

typescript
Copied
1
import airplane from "airplane";
2

3
export default airplane.task(
4
  {
5
    slug: "custom_timeout",
6
  },
7
  async () => {
8
    // ...
9

10
    const prompt = await airplane.prompt.background({
11
      ok: {
12
        type: "boolean",
13
        description: "Are you sure you want to continue?",
14
      },
15
    });
16

17
    // Wait for the prompt to be submitted, or for an hour to pass.
18
    await Promise.race([airplane.sleep("1h"), prompt.wait()]);
19

20
    if (!prompt.ok) {
21
      console.log("Prompt not approved.");
22
      return;
23
    }
24

25
    const run = await airplane.execute("my_task");
26
    return run.output;
27
  }
28
);