Wait for Token

Waitpoint tokens pause a task run indefinitely until you signal it to continue. While a run is waiting, it releases its compute slot — you are not billed for idle time. When you complete the token, the run resumes exactly where it left off. Common use cases:

Human approval — pause a content pipeline until a moderator approves
External webhook callback — pause until Replicate, Stripe, or another service posts a result
Multi-step forms — pause an onboarding flow until a user completes the next step
Async third-party jobs — kick off a long job and wait for the completion webhook

If you are waiting for typed data from an input stream, use inputStream.wait() instead — it wraps waitpoint tokens with full type safety.

Basic usage

Create a token

Create a token from anywhere in your codebase — inside or outside a task:

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

const token = await wait.createToken({
  timeout: "24h", // optional: auto-complete with a timeout error after 24 hours
  tags: ["moderation", "user:123"], // optional: visible in the dashboard
});

// token.id  — pass this to wait.forToken()
// token.url — POST to this URL to complete the token from any HTTP client

Wait for the token inside a task

Inside your task’s run function, call wait.forToken() with the token ID. The task suspends here until the token is completed or times out:

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

type ApprovalResult = {
  approved: boolean;
  comment?: string;
};

export const moderationTask = task({
  id: "moderation",
  run: async (payload: { content: string }) => {
    const token = await wait.createToken({ timeout: "24h" });

    // Notify your moderation team — send token.id or token.url
    await sendToModerationQueue({ content: payload.content, tokenId: token.id });

    // Task suspends here. Compute slot is released.
    const result = await wait.forToken<ApprovalResult>(token.id);

    if (!result.ok) {
      // Token timed out
      return { status: "timed_out" };
    }

    return {
      status: result.output.approved ? "approved" : "rejected",
      comment: result.output.comment,
    };
  },
});

async function sendToModerationQueue(opts: { content: string; tokenId: string }) {
  // send email, Slack message, etc.
}

Complete the token

When you are ready to resume the run, complete the token from your backend, a webhook handler, or any HTTP client:

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

await wait.completeToken<ApprovalResult>(tokenId, {
  approved: true,
  comment: "Looks good!",
});

Using `.unwrap()`

wait.forToken() returns a result object ({ ok, output } or { ok, error }). Use .unwrap() to skip the if (result.ok) check — it throws automatically if the token timed out:

// Without unwrap:
const result = await wait.forToken<ApprovalResult>(token.id);
if (!result.ok) throw result.error;
const approval = result.output;

// With unwrap (equivalent, but cleaner happy path):
const approval = await wait.forToken<ApprovalResult>(token.id).unwrap();
console.log(approval.approved); // boolean

Completing via HTTP webhook

The token’s url property is an HTTP callback URL. POST a JSON body to it to complete the token from any service or language. The request body becomes the token’s output:

const token = await wait.createToken({ timeout: "10m" });

// Pass token.url as a webhook URL to an external service
const prediction = await replicate.predictions.create({
  version: "27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478",
  input: { prompt: "A painting of a cat by Andy Warhol" },
  webhook: token.url,
  webhook_events_filter: ["completed"],
});

// The task resumes when Replicate POSTs to token.url
const result = await wait.forToken<typeof prediction>(token.id).unwrap();

You can also complete tokens via the REST API from any language:

curl -X POST "https://api.trigger.dev/api/v1/waitpoints/tokens/{tokenId}/complete" \
  -H "Authorization: Bearer {your-secret-key}" \
  -H "Content-Type: application/json" \
  -d '{"data": {"approved": true, "comment": "LGTM"}}'

import requests

response = requests.post(
  f"https://api.trigger.dev/api/v1/waitpoints/tokens/{token_id}/complete",
  headers={"Authorization": f"Bearer {secret_key}"},
  json={"data": {"approved": True, "comment": "LGTM"}},
)

require "net/http"
require "json"

uri = URI("https://api.trigger.dev/api/v1/waitpoints/tokens/#{token_id}/complete")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{secret_key}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({ data: { approved: true, comment: "LGTM" } })

response = http.request(request)

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
)

func completeToken(tokenID, secretKey string) error {
  payload := map[string]interface{}{
    "data": map[string]interface{}{
      "approved": true,
      "comment":  "LGTM",
    },
  }

  body, _ := json.Marshal(payload)
  url := fmt.Sprintf("https://api.trigger.dev/api/v1/waitpoints/tokens/%s/complete", tokenID)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+secretKey)
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    return err
  }
  defer resp.Body.Close()

  fmt.Println("Response status:", resp.Status)
  return nil
}

API reference

wait.createToken

Create a waitpoint token. Can be called from inside or outside a task.

const token = await wait.createToken({
  timeout: "10m",          // optional, defaults to "10m"
  idempotencyKey: "key",   // optional
  idempotencyKeyTTL: "1h", // optional, defaults to "1h"
  tags: ["tag1", "tag2"],  // optional
});

Returns:

Property	Type	Description
`id`	`string`	Token ID (starts with `waitpoint_`)
`url`	`string`	HTTP callback URL — POST to this to complete the token
`isCached`	`boolean`	`true` if an idempotency key matched an existing token
`publicAccessToken`	`string`	A Public Access Token scoped to this token

wait.forToken

Suspend the current task run until the token is completed or times out. Must be called inside a task’s run function.

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

if (result.ok) {
  console.log(result.output); // YourOutputType
} else {
  console.log(result.error);  // WaitpointTimeoutError
}

// Or use .unwrap() to throw on timeout:
const output = await wait.forToken<YourOutputType>(tokenId).unwrap();

wait.completeToken

Complete a token with an output payload. Can be called from anywhere.

await wait.completeToken<YourOutputType>(tokenId, {
  /* your payload */
});

wait.retrieveToken

Fetch the current state and output of a token by its ID.

const token = await wait.retrieveToken(tokenId);
// token.status: "WAITING" | "COMPLETED" | "TIMED_OUT"
// token.output — the data passed to completeToken()
// token.error  — set if status is "TIMED_OUT"

wait.listTokens

List tokens with optional filtering. Returns an async iterable — iterate with for await:

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

for await (const token of wait.listTokens({
  status: "WAITING",
  tags: ["moderation"],
  period: "1h",
})) {
  console.log(token.id, token.status);
}

Idempotency

Pass an idempotencyKey to createToken to avoid creating duplicate tokens if your code runs more than once (e.g. on a task retry):

const token = await wait.createToken({
  idempotencyKey: `approve-${documentId}`,
  idempotencyKeyTTL: "24h",
  timeout: "24h",
});
// If the same key is used again within the TTL, the original token is returned.
// token.isCached === true in that case

Next steps

Building with AI

Human-in-the-loop patterns for AI agent workflows.

React hooks

Resume tokens from the browser using the useWaitToken hook.

Realtime overview

Stream task output to your frontend in real-time.

Getting Started

Writing Tasks

AI Agents & Realtime

Configuration & Deployment

Observability & Management

Self-hosting

Basic usage

Using `.unwrap()`

Completing via HTTP webhook

API reference

wait.createToken

wait.forToken

wait.completeToken

wait.retrieveToken

wait.listTokens

Idempotency

Next steps

Building with AI

React hooks

Realtime overview

​Basic usage

​Using .unwrap()

​Completing via HTTP webhook

​API reference

​wait.createToken

​wait.forToken

​wait.completeToken

​wait.retrieveToken

​wait.listTokens

​Idempotency

​Next steps

Building with AI

React hooks

Realtime overview

Basic usage

Using `.unwrap()`

Completing via HTTP webhook

API reference

wait.createToken

wait.forToken

wait.completeToken

wait.retrieveToken

wait.listTokens

Idempotency

Next steps