Waitpoint tokens pause task runs until you complete the token. They’re commonly used for approval workflows and other scenarios where you need to wait for external confirmation, such as human-in-the-loop processes.

This feature is only available in the v4 beta. To upgrade to v4, see the upgrade to v4 docs.

​
Usage

To get started using wait tokens, you need to first create a token using the wait.createToken function:

import { wait } from "@trigger.dev/sdk";

// This can be called anywhere in your codebase, either in a task or in your backend code
const token = await wait.createToken({
  timeout: "10m", // you can optionally specify a timeout for the token
});

Once you have a token, you can wait for it to be completed using the wait.forToken function:

import { wait } from "@trigger.dev/sdk";

type ApprovalToken = {
  status: "approved" | "rejected";
};

// This must be called inside a task run function
const result = await wait.forToken<ApprovalToken>(tokenId);

if (result.ok) {
  console.log("Token completed", result.output.status); // "approved" or "rejected"
} else {
  console.log("Token timed out", result.error);
}

To complete a token, you can use the wait.completeToken function:

import { wait } from "@trigger.dev/sdk";
// This can be called anywhere in your codebase, or from an external service,
// passing in the token ID and the output of the token
await wait.completeToken<ApprovalToken>(tokenId, {
  status: "approved",
});

​
wait.createToken

Create a waitpoint token.

​
options

The createToken function accepts an object with the following properties:

​
timeout
string

The maximum amount of time to wait for the token to be completed. Defaults to “10m”.

​
idempotencyKey
string

An idempotency key for the token. If provided, the token will be completed with the same payload if the same idempotency key is used again.

​
idempotencyKeyTTL
string

The time to live for the idempotency key. Defaults to “1h”.

​
tags
string[]

Tags to attach to the token. Tags can be used to filter waitpoints in the dashboard.

​
returns

The createToken function returns a token object with the following properties:

​
id
string

The ID of the token. Starts with waitpoint_.

​
isCached
boolean

Whether the token is cached. Will return true if the token was created with an idempotency key and the same idempotency key was used again.

​
publicAccessToken
string

A Public Access Token that can be used to complete the token from a client-side application (or another backend). See our frontend docs for more details.

​
Example

import { wait } from "@trigger.dev/sdk";

const token = await wait.createToken({
  timeout: "10m",
  idempotencyKey: "my-idempotency-key",
  tags: ["my-tag"],
});

​
wait.completeToken

Complete a waitpoint token.

​
parameters

​
id
string

The ID of the token to complete.

​
output
any

The data to complete the token with.

​
returns

The completeToken function returns an object with the following properties:

​
success
boolean

Whether the token was completed successfully.

​
Example

import { wait } from "@trigger.dev/sdk";

await wait.completeToken<ApprovalToken>(tokenId, {
  status: "approved",
});

​
From another language

You can complete a token using a raw HTTP request or from another language.

curl -X POST "https://api.trigger.dev/api/v1/waitpoints/tokens/{tokenId}/complete" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"output": { "status": "approved"}}'

​
wait.forToken

Wait for a token to be completed.

​
parameters

​
token
string | { id: string }

The token to wait for.

​
options
object

Options for the wait.

​
returns

The forToken function returns a result object with the following properties:

​
ok
boolean

Whether the token was completed successfully.

​
output
any

If ok is true, this will be the output of the token.

​
error
Error

If ok is false, this will be the error that occurred. The only error that can occur is a timeout error.

​
Example

import { wait } from "@trigger.dev/sdk";

const result = await wait.forToken<ApprovalToken>(tokenId);

if (result.ok) {
  console.log("Token completed", result.output.status); // "approved" or "rejected"
} else {
  console.log("Token timed out", result.error);
}

​
wait.listTokens

List all tokens for an environment.

​
parameters

The listTokens function accepts an object with the following properties:

​
status
string | string[]

Statuses to filter by. Can be one or more of: WAITING, COMPLETED, TIMED_OUT.

​
idempotencyKey
string

The idempotency key to filter by.

​
tags
string | string[]

Tags to filter by.

​
period
string

The period to filter by. Can be one of: 1h, 1d, 7d, 30d.

​
from
Date | number

The start date to filter by.

​
to
Date | number

The end date to filter by.

​
returns

The listTokens function returns a list of tokens that can be iterated over using a for-await-of loop.

Each token is an object with the following properties:

​
id
string

The ID of the token.

​
status
string

The status of the token.

​
completedAt
Date

The date and time the token was completed.

​
timeoutAt
Date

The date and time the token will timeout.

​
idempotencyKey
string

The idempotency key of the token.

​
idempotencyKeyExpiresAt
Date

The date and time the idempotency key will expire.

​
tags
string[]

The tags of the token.

​
createdAt
Date

The date and time the token was created.

The output of the token is not included in the list. To get the output, you need to retrieve the token using the wait.retrieveToken function.

​
Example

import { wait } from "@trigger.dev/sdk";

const tokens = await wait.listTokens({
  status: "COMPLETED",
  tags: ["user:123"],
});

for await (const token of tokens) {
  console.log(token);
}

​
wait.retrieveToken

Retrieve a token by ID.

​
parameters

​
id
string

The ID of the token to retrieve.

​
returns

The retrieveToken function returns a token object with the following properties:

​
id
string

The ID of the token.

​
status
string

The status of the token.

​
completedAt
Date

The date and time the token was completed.

​
timeoutAt
Date

The date and time the token will timeout.

​
idempotencyKey
string

The idempotency key of the token.

​
idempotencyKeyExpiresAt
Date

The date and time the idempotency key will expire.

​
tags
string[]

The tags of the token.

​
createdAt
Date

The date and time the token was created.

​
output
any

The output of the token.

​
error
Error

The error that occurred.

​
Example

import { wait } from "@trigger.dev/sdk";

const token = await wait.retrieveToken(tokenId);

console.log(token);

Was this page helpful?

Suggest editsRaise issue