@trigger.dev/sdk 0.0.0-prerelease-20260911153544 → 0.0.0-prerelease-windows-bundle-fix-20260928100448
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commonjs/v3/ai.d.ts +37 -12
- package/dist/commonjs/v3/ai.js +349 -278
- package/dist/commonjs/v3/ai.js.map +1 -1
- package/dist/commonjs/v3/auth.js +8 -2
- package/dist/commonjs/v3/auth.js.map +1 -1
- package/dist/commonjs/v3/chat-client.js +7 -0
- package/dist/commonjs/v3/chat-client.js.map +1 -1
- package/dist/commonjs/v3/chat-server.d.ts +1 -0
- package/dist/commonjs/v3/chat-server.js +8 -0
- package/dist/commonjs/v3/chat-server.js.map +1 -1
- package/dist/commonjs/v3/chat.js +13 -9
- package/dist/commonjs/v3/chat.js.map +1 -1
- package/dist/commonjs/v3/compactionResponse.d.ts +9 -0
- package/dist/commonjs/v3/compactionResponse.js +37 -0
- package/dist/commonjs/v3/compactionResponse.js.map +1 -0
- package/dist/commonjs/v3/concurrency-shared.d.ts +13 -0
- package/dist/commonjs/v3/concurrency-shared.js +35 -0
- package/dist/commonjs/v3/concurrency-shared.js.map +1 -0
- package/dist/commonjs/v3/concurrencyLimits.d.ts +73 -0
- package/dist/commonjs/v3/concurrencyLimits.js +166 -0
- package/dist/commonjs/v3/concurrencyLimits.js.map +1 -0
- package/dist/commonjs/v3/index.d.ts +2 -1
- package/dist/commonjs/v3/index.js +3 -1
- package/dist/commonjs/v3/index.js.map +1 -1
- package/dist/commonjs/v3/managedChatResponse.d.ts +44 -0
- package/dist/commonjs/v3/managedChatResponse.js +233 -0
- package/dist/commonjs/v3/managedChatResponse.js.map +1 -0
- package/dist/commonjs/v3/queues.d.ts +31 -0
- package/dist/commonjs/v3/queues.js +31 -0
- package/dist/commonjs/v3/queues.js.map +1 -1
- package/dist/commonjs/v3/runs.d.ts +5 -0
- package/dist/commonjs/v3/sessionTracing.d.ts +7 -0
- package/dist/commonjs/v3/sessionTracing.js +44 -0
- package/dist/commonjs/v3/sessionTracing.js.map +1 -0
- package/dist/commonjs/v3/sessions.js +31 -34
- package/dist/commonjs/v3/sessions.js.map +1 -1
- package/dist/commonjs/v3/shared.d.ts +18 -1
- package/dist/commonjs/v3/shared.js +145 -52
- package/dist/commonjs/v3/shared.js.map +1 -1
- package/dist/commonjs/v3/steeringContext.d.ts +41 -0
- package/dist/commonjs/v3/steeringContext.js +118 -0
- package/dist/commonjs/v3/steeringContext.js.map +1 -0
- package/dist/commonjs/v3/transcriptStorage.d.ts +4 -1
- package/dist/commonjs/v3/transcriptStorage.js +55 -4
- package/dist/commonjs/v3/transcriptStorage.js.map +1 -1
- package/dist/commonjs/version.js +1 -1
- package/dist/esm/v3/ai.d.ts +37 -12
- package/dist/esm/v3/ai.js +350 -279
- package/dist/esm/v3/ai.js.map +1 -1
- package/dist/esm/v3/auth.js +8 -2
- package/dist/esm/v3/auth.js.map +1 -1
- package/dist/esm/v3/chat-client.js +7 -0
- package/dist/esm/v3/chat-client.js.map +1 -1
- package/dist/esm/v3/chat-server.d.ts +1 -0
- package/dist/esm/v3/chat-server.js +8 -0
- package/dist/esm/v3/chat-server.js.map +1 -1
- package/dist/esm/v3/chat.js +13 -9
- package/dist/esm/v3/chat.js.map +1 -1
- package/dist/esm/v3/compactionResponse.d.ts +9 -0
- package/dist/esm/v3/compactionResponse.js +34 -0
- package/dist/esm/v3/compactionResponse.js.map +1 -0
- package/dist/esm/v3/concurrency-shared.d.ts +13 -0
- package/dist/esm/v3/concurrency-shared.js +31 -0
- package/dist/esm/v3/concurrency-shared.js.map +1 -0
- package/dist/esm/v3/concurrencyLimits.d.ts +73 -0
- package/dist/esm/v3/concurrencyLimits.js +158 -0
- package/dist/esm/v3/concurrencyLimits.js.map +1 -0
- package/dist/esm/v3/index.d.ts +2 -1
- package/dist/esm/v3/index.js +2 -1
- package/dist/esm/v3/index.js.map +1 -1
- package/dist/esm/v3/managedChatResponse.d.ts +44 -0
- package/dist/esm/v3/managedChatResponse.js +228 -0
- package/dist/esm/v3/managedChatResponse.js.map +1 -0
- package/dist/esm/v3/queues.d.ts +31 -0
- package/dist/esm/v3/queues.js +31 -0
- package/dist/esm/v3/queues.js.map +1 -1
- package/dist/esm/v3/runs.d.ts +5 -0
- package/dist/esm/v3/sessionTracing.d.ts +7 -0
- package/dist/esm/v3/sessionTracing.js +40 -0
- package/dist/esm/v3/sessionTracing.js.map +1 -0
- package/dist/esm/v3/sessions.js +31 -34
- package/dist/esm/v3/sessions.js.map +1 -1
- package/dist/esm/v3/shared.d.ts +18 -1
- package/dist/esm/v3/shared.js +145 -53
- package/dist/esm/v3/shared.js.map +1 -1
- package/dist/esm/v3/steeringContext.d.ts +41 -0
- package/dist/esm/v3/steeringContext.js +113 -0
- package/dist/esm/v3/steeringContext.js.map +1 -0
- package/dist/esm/v3/transcriptStorage.d.ts +4 -1
- package/dist/esm/v3/transcriptStorage.js +55 -5
- package/dist/esm/v3/transcriptStorage.js.map +1 -1
- package/dist/esm/version.js +1 -1
- package/docs/ai-chat/anatomy.mdx +44 -24
- package/docs/ai-chat/client-protocol.mdx +2 -0
- package/docs/ai-chat/error-handling.mdx +44 -76
- package/docs/ai-chat/frontend.mdx +27 -21
- package/docs/ai-chat/lifecycle-hooks.mdx +4 -2
- package/docs/ai-chat/patterns/branching-conversations.mdx +95 -230
- package/docs/ai-chat/patterns/human-in-the-loop.mdx +166 -164
- package/docs/ai-chat/patterns/tool-result-auditing.mdx +28 -27
- package/docs/ai-chat/pending-messages.mdx +19 -5
- package/docs/ai-chat/quick-start.mdx +26 -20
- package/docs/ai-chat/reference.mdx +4 -2
- package/docs/ai-chat/testing.mdx +16 -4
- package/docs/cli-env-commands.mdx +114 -0
- package/docs/cli-projects-commands.mdx +62 -0
- package/docs/cli-runs-commands.mdx +94 -0
- package/docs/concurrency.mdx +384 -0
- package/docs/database-connections.mdx +3 -3
- package/docs/deploy-environment-variables.mdx +6 -0
- package/docs/idempotency.mdx +43 -5
- package/docs/introduction.mdx +58 -152
- package/docs/limits.mdx +16 -6
- package/docs/observability/query.mdx +25 -0
- package/docs/queues.mdx +248 -0
- package/docs/reports.mdx +1 -1
- package/docs/runs/priority.mdx +2 -25
- package/docs/self-hosting/env/webapp.mdx +7 -0
- package/docs/tasks/overview.mdx +3 -5
- package/docs/troubleshooting-alerts.mdx +124 -1
- package/docs/troubleshooting.mdx +12 -0
- package/docs/writing-tasks-introduction.mdx +2 -1
- package/package.json +2 -2
- package/docs/queue-concurrency.mdx +0 -358
package/docs/introduction.mdx
CHANGED
|
@@ -1,181 +1,69 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
2
|
+
title: "Trigger.dev docs"
|
|
3
3
|
sidebarTitle: "Introduction"
|
|
4
|
-
description: "
|
|
4
|
+
description: "Build and run durable AI agents and workflows in TypeScript. Long-running tasks with retries, queues, observability, and elastic scaling. Open source and self-hostable."
|
|
5
5
|
mode: "center"
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
<CardGroup cols={2}>
|
|
9
|
-
<Card title="Quick start"
|
|
10
|
-
|
|
9
|
+
<Card title="Quick start" icon="rocket" href="/quick-start" color="#A8FF53">
|
|
10
|
+
Go from zero to your first task in 3 minutes.
|
|
11
11
|
</Card>
|
|
12
|
-
<Card
|
|
13
|
-
|
|
14
|
-
img="/images/intro-examples.jpg"
|
|
15
|
-
href="/guides/introduction#example-tasks"
|
|
16
|
-
>
|
|
17
|
-
Browse our wide range of guides, frameworks and example projects
|
|
12
|
+
<Card title="Build AI agents" icon="robot" href="/guides/ai-agents/overview" color="#a855f7">
|
|
13
|
+
Agent patterns, worked examples, and the tools to run them in production.
|
|
18
14
|
</Card>
|
|
19
|
-
<Card title="
|
|
20
|
-
|
|
15
|
+
<Card title="AI coding assistants" icon="wand-magic-sparkles" href="/building-with-ai" color="#3B82F6">
|
|
16
|
+
Let Claude Code, Cursor and Windsurf write correct Trigger.dev code with the MCP server, Skills and rules.
|
|
21
17
|
</Card>
|
|
22
|
-
<Card title="
|
|
23
|
-
|
|
18
|
+
<Card title="Guides & examples" icon="book-open" href="/guides/introduction" color="#f6cd46">
|
|
19
|
+
Frameworks like Next.js, worked example projects, and step-by-step how-to guides.
|
|
24
20
|
</Card>
|
|
25
21
|
</CardGroup>
|
|
26
22
|
|
|
27
23
|
## What is Trigger.dev?
|
|
28
24
|
|
|
29
|
-
Trigger.dev is
|
|
25
|
+
Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. Run them for hours, configure automatic retries, control concurrency, and manage queues. There's no execution timeout, and no queue or worker infrastructure for you to build.
|
|
26
|
+
|
|
27
|
+
You write agents and tasks in your existing codebase using our CLI and SDK, and get durable execution, queues, waits, full tracing, and elastic scaling without building any of it yourself.
|
|
30
28
|
|
|
31
|
-
|
|
29
|
+
Trigger.dev's core is Apache-2.0 licensed, a genuine OSI license. [Self-host it](/self-hosting/overview) on your own infrastructure, or let [Trigger.dev Cloud](https://cloud.trigger.dev) run it for you.
|
|
32
30
|
|
|
33
|
-
##
|
|
31
|
+
## Core concepts
|
|
34
32
|
|
|
35
33
|
<CardGroup cols={2}>
|
|
36
|
-
<Card title="Writing tasks" icon="
|
|
37
|
-
|
|
34
|
+
<Card title="Writing tasks" icon="pen-to-square" href="/tasks/overview" color="#A8FF53">
|
|
35
|
+
The durable functions at the core of Trigger.dev. Write them in your existing codebase, with retries and no timeouts.
|
|
38
36
|
</Card>
|
|
39
|
-
<Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#
|
|
40
|
-
|
|
37
|
+
<Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#3b82f6">
|
|
38
|
+
Trigger a task from your backend, your frontend, a schedule, or another task.
|
|
41
39
|
</Card>
|
|
42
|
-
<Card title="Runs" icon="
|
|
43
|
-
|
|
40
|
+
<Card title="Runs" icon="play" href="/runs" color="#28bf5c">
|
|
41
|
+
Every execution of a task is a run, with its status, retries, and logs recorded.
|
|
44
42
|
</Card>
|
|
45
|
-
<Card title="
|
|
46
|
-
|
|
47
|
-
them.
|
|
43
|
+
<Card title="Idempotency" icon="fingerprint" href="/idempotency" color="#F43F5E">
|
|
44
|
+
Use an idempotency key so a retried or duplicated trigger runs once, not twice.
|
|
48
45
|
</Card>
|
|
49
46
|
</CardGroup>
|
|
50
47
|
|
|
51
|
-
##
|
|
48
|
+
## Build with agents
|
|
52
49
|
|
|
53
|
-
|
|
54
|
-
<Card title="Scheduled tasks (cron)" icon="clock" href="/tasks/scheduled" color="#EAEA08">
|
|
55
|
-
Scheduled tasks are a type of task that is scheduled to run at a specific time.
|
|
56
|
-
</Card>
|
|
57
|
-
<Card title="Realtime API" icon="loader" href="/realtime" color="#22C55E">
|
|
58
|
-
The Realtime API allows you to trigger tasks and get the status of runs.
|
|
59
|
-
</Card>
|
|
60
|
-
<Card title="React hooks" icon="react" href="/realtime/react-hooks" color="#3B82F6">
|
|
61
|
-
React hooks are a way to show task status in your frontend.
|
|
62
|
-
</Card>
|
|
63
|
-
<Card title="Waits" icon="calendar-clock" href="/wait" color="#F59E0B">
|
|
64
|
-
Waits are a way to wait for a task to finish before continuing.
|
|
65
|
-
</Card>
|
|
66
|
-
<Card
|
|
67
|
-
title="Errors and retries"
|
|
68
|
-
icon="message-exclamation"
|
|
69
|
-
href="/errors-retrying"
|
|
70
|
-
color="#F43F5E"
|
|
71
|
-
>
|
|
72
|
-
Learn how to handle errors and retries.
|
|
73
|
-
</Card>
|
|
74
|
-
<Card title="Concurrency & Queues" icon="line-height" href="/queue-concurrency" color="#D946EF">
|
|
75
|
-
Configure what you want to happen when there is more than one run at a time.
|
|
76
|
-
</Card>
|
|
77
|
-
<Card
|
|
78
|
-
title="Wait for token (human-in-the-loop)"
|
|
79
|
-
icon="hand"
|
|
80
|
-
href="/wait-for-token"
|
|
81
|
-
color="#EAEA08"
|
|
82
|
-
>
|
|
83
|
-
Pause runs until a token is completed via an approval workflow.
|
|
84
|
-
</Card>
|
|
85
|
-
<Card title="Build extensions" icon="gear" href="/config/extensions/overview" color="#22C55E">
|
|
86
|
-
Customize the build process or the resulting bundle and container image.
|
|
87
|
-
</Card>
|
|
88
|
-
</CardGroup>
|
|
50
|
+
Build durable, multi-turn agents with the [chat agent](/ai-chat/overview): one long-running task per conversation, with the tools it can call, streaming, and resumability handled for you. Add human-in-the-loop approval by pausing a run on a [waitpoint](/wait-for-token) until a person signs off, and a waiting run doesn't consume compute. Stream run status and LLM output straight to your frontend with the [Realtime API](/realtime/overview) and React hooks, and record your Vercel AI SDK calls as spans with the model, token counts, cost and latency using [AI observability](/ai/observability). Version your [prompts](/ai/prompts) in code, then edit the text or swap the model from the dashboard without redeploying.
|
|
89
51
|
|
|
90
|
-
##
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
| emitDecoratorMetadata | Support for the emitDecoratorMetadata TypeScript compiler | [emitDecoratorMetadata docs](/config/extensions/emitDecoratorMetadata) |
|
|
106
|
-
| audioWaveform | Support for Audio Waveform in your project | [audioWaveform docs](/config/extensions/audioWaveform) |
|
|
107
|
-
|
|
108
|
-
## Explore by example
|
|
109
|
-
|
|
110
|
-
<CardGroup cols={3}>
|
|
111
|
-
<Card
|
|
112
|
-
title="FFmpeg"
|
|
113
|
-
img="/images/intro-ffmpeg.jpg"
|
|
114
|
-
href="/guides/examples/ffmpeg-video-processing"
|
|
115
|
-
/>
|
|
116
|
-
<Card
|
|
117
|
-
title="Fal.ai"
|
|
118
|
-
img="/images/intro-fal.jpg"
|
|
119
|
-
href="/guides/examples/fal-ai-image-to-cartoon"
|
|
120
|
-
/>
|
|
121
|
-
<Card title="Puppeteer" img="/images/intro-puppeteer.jpg" href="/guides/examples/puppeteer" />
|
|
122
|
-
<Card
|
|
123
|
-
title="LibreOffice"
|
|
124
|
-
img="/images/intro-libreoffice.jpg"
|
|
125
|
-
href="/guides/examples/libreoffice-pdf-conversion"
|
|
126
|
-
/>
|
|
127
|
-
<Card
|
|
128
|
-
title="OpenAI"
|
|
129
|
-
img="/images/intro-openai.jpg"
|
|
130
|
-
href="/guides/examples/open-ai-with-retrying"
|
|
131
|
-
/>
|
|
132
|
-
<Card
|
|
133
|
-
title="Browserbase"
|
|
134
|
-
img="/images/intro-browserbase.jpg"
|
|
135
|
-
href="/guides/examples/scrape-hacker-news"
|
|
136
|
-
/>
|
|
137
|
-
<Card
|
|
138
|
-
title="Sentry"
|
|
139
|
-
img="/images/intro-sentry.jpg"
|
|
140
|
-
href="/guides/examples/sentry-error-tracking"
|
|
141
|
-
/>
|
|
142
|
-
<Card
|
|
143
|
-
title="Resend"
|
|
144
|
-
img="/images/intro-resend.jpg"
|
|
145
|
-
href="/guides/examples/resend-email-sequence"
|
|
146
|
-
/>
|
|
147
|
-
<Card
|
|
148
|
-
title="Vercel AI SDK"
|
|
149
|
-
img="/images/intro-vercel.jpg"
|
|
150
|
-
href="/guides/examples/vercel-ai-sdk"
|
|
151
|
-
/>
|
|
152
|
-
<Card
|
|
153
|
-
title="Sharp"
|
|
154
|
-
img="/images/intro-sharp.jpg"
|
|
155
|
-
href="/guides/examples/sharp-image-processing"
|
|
156
|
-
/>
|
|
157
|
-
<Card
|
|
158
|
-
title="Deepgram"
|
|
159
|
-
img="/images/intro-deepgram.jpg"
|
|
160
|
-
href="/guides/examples/deepgram-transcribe-audio"
|
|
161
|
-
/>
|
|
162
|
-
<Card
|
|
163
|
-
title="Supabase"
|
|
164
|
-
img="/images/intro-supabase.jpg"
|
|
165
|
-
href="/guides/examples/supabase-database-operations"
|
|
166
|
-
/>
|
|
167
|
-
<Card
|
|
168
|
-
title="DALL•E"
|
|
169
|
-
img="/images/intro-openai.jpg"
|
|
170
|
-
href="/guides/examples/dall-e3-generate-image"
|
|
171
|
-
/>
|
|
172
|
-
<Card
|
|
173
|
-
title="Firecrawl"
|
|
174
|
-
img="/images/intro-firecrawl.jpg"
|
|
175
|
-
href="/guides/examples/firecrawl-url-crawl"
|
|
176
|
-
/>
|
|
177
|
-
<Card title="Lightpanda" img="/images/intro-lightpanda.jpg" href="/guides/examples/lightpanda" />
|
|
178
|
-
</CardGroup>
|
|
52
|
+
## Scale and scheduling
|
|
53
|
+
|
|
54
|
+
Set how many runs of a task execute at once, globally or per tenant, with [concurrency](/concurrency) and [queues](/queues). Run a task on a [cron schedule](/tasks/scheduled) with timezone support, choose the CPU and memory each task runs on with [machines](/machines), and control what happens when a task throws with [errors and retries](/errors-retrying).
|
|
55
|
+
|
|
56
|
+
## Self-hosting
|
|
57
|
+
|
|
58
|
+
Trigger.dev is open source and you can self-host. Read the [overview guide](/self-hosting/overview), or how to do it with [Docker](/self-hosting/docker) or [Kubernetes](/self-hosting/kubernetes).
|
|
59
|
+
|
|
60
|
+
## Frequently asked questions
|
|
61
|
+
|
|
62
|
+
**How do I add human-in-the-loop approval to an agent?** Pause the run on a [waitpoint](/wait-for-token) until a person approves the action. A waiting run doesn't consume compute, so it can wait minutes or days.
|
|
63
|
+
|
|
64
|
+
**Does Trigger.dev support tool calling and MCP?** Yes. Agents call the tools you define, and the [MCP server](/building-with-ai) lets AI coding assistants trigger tasks, deploy, and read run traces.
|
|
65
|
+
|
|
66
|
+
**Can I use Trigger.dev for background jobs, not just AI?** Yes. The same durable tasks, queues, retries, and [cron schedules](/tasks/scheduled) run any background job or workflow, with or without AI.
|
|
179
67
|
|
|
180
68
|
## Getting help
|
|
181
69
|
|
|
@@ -221,3 +109,21 @@ We'd love to hear from you or give you a hand getting started. Here are some way
|
|
|
221
109
|
Check us out our GitHub repo and give us a star if you like what we're doing.
|
|
222
110
|
</Card>
|
|
223
111
|
</CardGroup>
|
|
112
|
+
|
|
113
|
+
<Visibility for="agents">
|
|
114
|
+
|
|
115
|
+
## Facts for AI assistants
|
|
116
|
+
|
|
117
|
+
**Current major version:** v4 (`@trigger.dev/sdk` 4.x). Documentation under `/docs/v2` and `/docs/v3` describes superseded versions and should not be used.
|
|
118
|
+
|
|
119
|
+
**Execution model:** tasks run on Trigger.dev infrastructure, not inside your serverless functions, so a platform function timeout is not in the execution path. A task runs until it finishes; you can cap runtime with `maxDuration` (minimum 5 seconds).
|
|
120
|
+
|
|
121
|
+
**Deploys:** each deploy is an atomic version. A run already in progress is not affected by code shipped after it started.
|
|
122
|
+
|
|
123
|
+
**Durability and retries:** retries are automatic and configurable. A failed attempt is retried according to the task's retry settings; once retries are exhausted the run ends terminally as `FAILED`, and some crashes (for example out of memory) end the run as `CRASHED` without a retry. Idempotency keys deduplicate the task triggers and waits you key, so the same key runs once instead of again.
|
|
124
|
+
|
|
125
|
+
**License:** the platform core is Apache-2.0 and the `@trigger.dev/sdk` package is MIT, permissive open source, not fair-code or source-available. Some features are gated, but the open source core is not relicensed or held back.
|
|
126
|
+
|
|
127
|
+
**LLM observability coverage:** only Vercel AI SDK calls (`generateText`, `streamText`, `generateObject`) are recorded as spans. Raw `fetch` calls and provider SDKs used directly are not captured.
|
|
128
|
+
|
|
129
|
+
</Visibility>
|
package/docs/limits.mdx
CHANGED
|
@@ -14,11 +14,15 @@ You can view your current limits, quotas, and rate limit usage in real-time by v
|
|
|
14
14
|
|
|
15
15
|
## Concurrency limits
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
|
20
|
-
|
|
|
21
|
-
|
|
|
17
|
+
Concurrency is allocated **per environment**, not as a single figure for the whole organization. Each plan sets a separate default for production, staging, preview and development:
|
|
18
|
+
|
|
19
|
+
| Pricing tier | Production | Staging | Preview | Development |
|
|
20
|
+
| :----------- | :--------- | :------ | :------ | :---------- |
|
|
21
|
+
| Free | 20 | 10 | 10 | 25 |
|
|
22
|
+
| Hobby | 50 | 25 | 25 | 25 |
|
|
23
|
+
| Pro | 200+ | 100 | 100 | 25 |
|
|
24
|
+
|
|
25
|
+
These are plan defaults. The limit actually enforced for one of your environments can be higher: purchased add-on concurrency and any manual increase we have applied are both included in it. The **Concurrency** page in the dashboard (left sidebar) is authoritative for your organization — if it disagrees with the table above, the dashboard is correct.
|
|
22
26
|
|
|
23
27
|
Extra concurrency above the Pro tier limit is available via the dashboard. Click the "Concurrency" page from the left sidebar when on the Pro plan to purchase more.
|
|
24
28
|
|
|
@@ -50,7 +54,13 @@ The maximum number of runs that can be queued **per queue** (not across all queu
|
|
|
50
54
|
|
|
51
55
|
## Maximum run TTL
|
|
52
56
|
|
|
53
|
-
On Trigger.dev Cloud, all runs have an enforced maximum TTL of 14 days. Runs without an explicit TTL automatically receive the 14-day TTL; runs with a TTL longer than 14 days are clamped to 14 days. This prevents queued runs from accumulating indefinitely.
|
|
57
|
+
On Trigger.dev Cloud, all runs have an enforced maximum TTL of 14 days. Runs without an explicit TTL automatically receive the 14-day TTL; runs with a TTL longer than 14 days are clamped to 14 days. This prevents queued runs from accumulating indefinitely.
|
|
58
|
+
|
|
59
|
+
**The TTL cap does not limit how far ahead you can schedule a run.** TTL governs how long a run may sit *queued* waiting for a concurrency slot. A run triggered with [`delay`](/triggering#delay) is not queued while it is delayed, and no TTL expiry is armed for it — the TTL clock only starts once the delay elapses and the run is enqueued. So scheduling a run a month out with `delay` works fine, and the 14 days then applies to how long it may wait for a slot after that month is up.
|
|
60
|
+
|
|
61
|
+
There is no maximum on `delay`.
|
|
62
|
+
|
|
63
|
+
If you self-host, you can configure a maximum TTL via the `RUN_ENGINE_DEFAULT_MAX_TTL` environment variable — see [Self-hosting environment variables](/self-hosting/env/webapp#run-engine).
|
|
54
64
|
|
|
55
65
|
## Schedules
|
|
56
66
|
|
|
@@ -28,6 +28,31 @@ description: "Query allows you to write custom queries against your data using T
|
|
|
28
28
|
|
|
29
29
|
See [Logging, tracing & metrics](/logging#automatic-system-and-runtime-metrics) for the full list of automatically collected metrics and how to create custom metrics. You can visualize this data on [Dashboards](/observability/dashboards).
|
|
30
30
|
|
|
31
|
+
#### API rate limit metrics
|
|
32
|
+
|
|
33
|
+
The `metrics` table also records how the API rate limiter treated requests made with your environment's secret API key, per environment and per `bucket_start` bucket:
|
|
34
|
+
|
|
35
|
+
- `api.rate_limit.allowed` (`sum`): requests that passed the rate limiter
|
|
36
|
+
- `api.rate_limit.denied` (`sum`): requests rejected with a 429
|
|
37
|
+
- `api.rate_limit.remaining_min` (`gauge`): the lowest remaining token count seen in the bucket
|
|
38
|
+
- `api.rate_limit.limit.per_second` (`gauge`): the sustained rate your limit refills at, in requests per second
|
|
39
|
+
- `api.rate_limit.limit.burst` (`gauge`): the most requests the limit admits at once
|
|
40
|
+
|
|
41
|
+
These rows have no run, task, or machine attributes (`run_id`, `task_identifier`, `machine_id` and so on are empty). Sum the counters over time, take `min()` of `api.rate_limit.remaining_min` and `max()` of the limit gauges. Total attempts in a bucket are `allowed + denied`. To draw the sustained limit for a bucket, multiply `api.rate_limit.limit.per_second` by that bucket's width in seconds; `timeBucket()` picks its width from the query's time range, so use a fixed `toStartOfMinute(bucket_start)` grouping when you want a known width (recording buckets never straddle a minute, so this grouping never splits a bucket; the example assumes a bucket width of at most one minute, which includes the default 10 seconds, and with a wider width you would group by that width and multiply by it instead). The limit gauges only exist in buckets that saw requests, and they follow any change to your limit, so a chart stays correct after an increase. Requests from preview branches share the parent preview environment's rate limit bucket and are recorded against that environment, so query at project scope to see them. Self-hosted instances enable recording with `API_RATE_LIMIT_METRICS_ENABLED=1`, or `allowlist` to record only organizations with the `apiRateLimitMetricsEnabled` feature flag.
|
|
42
|
+
|
|
43
|
+
```sql
|
|
44
|
+
SELECT
|
|
45
|
+
toStartOfMinute(bucket_start) AS minute,
|
|
46
|
+
sumIf(metric_value, metric_name IN ('api.rate_limit.allowed', 'api.rate_limit.denied')) AS attempts,
|
|
47
|
+
sumIf(metric_value, metric_name = 'api.rate_limit.denied') AS denied,
|
|
48
|
+
maxIf(metric_value, metric_name = 'api.rate_limit.limit.per_second') * 60 AS limit_per_minute
|
|
49
|
+
FROM metrics
|
|
50
|
+
WHERE metric_name LIKE 'api.rate_limit.%'
|
|
51
|
+
GROUP BY minute
|
|
52
|
+
ORDER BY minute
|
|
53
|
+
LIMIT 1000
|
|
54
|
+
```
|
|
55
|
+
|
|
31
56
|
### `prettyFormat()`
|
|
32
57
|
|
|
33
58
|
Use `prettyFormat()` to format metric values for display:
|
package/docs/queues.mdx
ADDED
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Queues"
|
|
3
|
+
description: "Control the order your runs execute in."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
import Priority from "/snippets/priority.mdx";
|
|
7
|
+
|
|
8
|
+
When you trigger a task, it isn't executed immediately. Instead, the task [run](/runs) is placed into a queue for execution. Runs in a queue are started in the order they were triggered, first in, first out, unless you give a run a [priority](#priority) at trigger time.
|
|
9
|
+
|
|
10
|
+
By default, each task gets its own queue, so triggering the same task ten times executes those runs in trigger order. How many of them execute *at once* is a separate question, governed by [concurrency](/concurrency) — your environment's concurrency limit, plus any limits you set on the task.
|
|
11
|
+
|
|
12
|
+
## Sharing a queue between tasks
|
|
13
|
+
|
|
14
|
+
Declare a queue with `queue()` and set it on several tasks to interleave their runs in one queue. Runs from every task on the queue start in the order they were triggered, whichever task they belong to:
|
|
15
|
+
|
|
16
|
+
```ts /trigger/emails.ts
|
|
17
|
+
import { queue, task } from "@trigger.dev/sdk";
|
|
18
|
+
|
|
19
|
+
const emailQueue = queue({ name: "emails" });
|
|
20
|
+
|
|
21
|
+
export const sendWelcomeEmail = task({
|
|
22
|
+
id: "send-welcome-email",
|
|
23
|
+
queue: emailQueue,
|
|
24
|
+
run: async (payload) => {
|
|
25
|
+
//...
|
|
26
|
+
},
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
export const sendDigestEmail = task({
|
|
30
|
+
id: "send-digest-email",
|
|
31
|
+
queue: emailQueue,
|
|
32
|
+
run: async (payload) => {
|
|
33
|
+
//...
|
|
34
|
+
},
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
<Note>
|
|
39
|
+
If what you want to share is a concurrency cap rather than ordering, you don't need a shared
|
|
40
|
+
queue: declare a named limit with `concurrencyLimit()` and each task keeps its own queue while
|
|
41
|
+
drawing from the shared limit. See [sharing a limit between
|
|
42
|
+
tasks](/concurrency#sharing-a-limit-between-tasks).
|
|
43
|
+
</Note>
|
|
44
|
+
|
|
45
|
+
Queue names can use letters, numbers, underscores, hyphens and slashes, up to 128 characters. Names starting with `limit/` are reserved for [concurrency limits](/concurrency) and are rejected at deploy time.
|
|
46
|
+
|
|
47
|
+
## Setting the queue when you trigger a run
|
|
48
|
+
|
|
49
|
+
When you trigger a task you can override its queue by name. This is really useful if you sometimes have high priority runs:
|
|
50
|
+
|
|
51
|
+
```ts /trigger/override-queue.ts
|
|
52
|
+
import { queue, task } from "@trigger.dev/sdk";
|
|
53
|
+
|
|
54
|
+
const paidQueue = queue({ name: "paid-users" });
|
|
55
|
+
|
|
56
|
+
export const generatePullRequest = task({
|
|
57
|
+
id: "generate-pull-request",
|
|
58
|
+
// normally this task is limited to 1 run at a time
|
|
59
|
+
concurrency: { total: 1 },
|
|
60
|
+
run: async (payload) => {
|
|
61
|
+
//todo generate a PR using OpenAI
|
|
62
|
+
},
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Triggering from your backend and overriding the queue:
|
|
67
|
+
|
|
68
|
+
```ts app/api/push/route.ts
|
|
69
|
+
import { generatePullRequest } from "~/trigger/override-queue";
|
|
70
|
+
|
|
71
|
+
export async function POST(request: Request) {
|
|
72
|
+
const data = await request.json();
|
|
73
|
+
|
|
74
|
+
if (data.branch === "main") {
|
|
75
|
+
//trigger the task, with the paid users queue
|
|
76
|
+
const handle = await generatePullRequest.trigger(data, {
|
|
77
|
+
// Set the paid users queue
|
|
78
|
+
queue: "paid-users",
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
return Response.json(handle);
|
|
82
|
+
} else {
|
|
83
|
+
//triggered with the default queue
|
|
84
|
+
const handle = await generatePullRequest.trigger(data);
|
|
85
|
+
return Response.json(handle);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Priority
|
|
91
|
+
|
|
92
|
+
You can re-order runs within a queue at trigger time by giving them a priority:
|
|
93
|
+
|
|
94
|
+
<Priority />
|
|
95
|
+
|
|
96
|
+
## Managing queues with the SDK
|
|
97
|
+
|
|
98
|
+
The SDK provides a `queues` namespace that allows you to manage queues programmatically. You can list, retrieve, pause, resume, and modify concurrency limits for queues.
|
|
99
|
+
|
|
100
|
+
<Note>
|
|
101
|
+
Import from `@trigger.dev/sdk`:
|
|
102
|
+
```ts
|
|
103
|
+
import { queues } from "@trigger.dev/sdk";
|
|
104
|
+
```
|
|
105
|
+
</Note>
|
|
106
|
+
|
|
107
|
+
### Listing queues
|
|
108
|
+
|
|
109
|
+
You can list all queues in your environment with pagination support:
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
import { queues } from "@trigger.dev/sdk";
|
|
113
|
+
|
|
114
|
+
// List all queues (returns paginated results)
|
|
115
|
+
const allQueues = await queues.list();
|
|
116
|
+
|
|
117
|
+
// With pagination options
|
|
118
|
+
const pagedQueues = await queues.list({
|
|
119
|
+
page: 1,
|
|
120
|
+
perPage: 20,
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Retrieving a queue
|
|
125
|
+
|
|
126
|
+
You can retrieve a specific queue by its ID, or by its type and name:
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
import { queues } from "@trigger.dev/sdk";
|
|
130
|
+
|
|
131
|
+
// Using queue ID (starts with "queue_")
|
|
132
|
+
const queueById = await queues.retrieve("queue_1234");
|
|
133
|
+
|
|
134
|
+
// Using type and name for a task's default queue
|
|
135
|
+
const taskQueue = await queues.retrieve({
|
|
136
|
+
type: "task",
|
|
137
|
+
name: "my-task-id",
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
// Using type and name for a custom queue
|
|
141
|
+
const customQueue = await queues.retrieve({
|
|
142
|
+
type: "custom",
|
|
143
|
+
name: "my-custom-queue",
|
|
144
|
+
});
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The queue object contains useful information about the queue state, and its `version` discriminates the shape:
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
// V1: the queue carries its own concurrency limit and override state
|
|
151
|
+
{
|
|
152
|
+
id: "queue_1234", // Queue ID
|
|
153
|
+
name: "my-task-id", // Queue name
|
|
154
|
+
type: "task", // "task" or "custom"
|
|
155
|
+
version: "V1",
|
|
156
|
+
running: 5, // Currently executing runs
|
|
157
|
+
queued: 10, // Runs waiting to execute
|
|
158
|
+
paused: false, // Whether the queue is paused
|
|
159
|
+
concurrencyLimit: 10, // The queue's own limit
|
|
160
|
+
concurrency: {
|
|
161
|
+
current: 10, // Effective limit
|
|
162
|
+
base: 10, // Default limit from code
|
|
163
|
+
override: null, // Override value (if set)
|
|
164
|
+
overriddenAt: null, // When override was applied
|
|
165
|
+
overriddenBy: null, // Who applied the override
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// V2: the queue is only the line runs wait in. Concurrency is declared with
|
|
170
|
+
// the task `concurrency` option and managed through `concurrencyLimits`.
|
|
171
|
+
{
|
|
172
|
+
id: "queue_5678",
|
|
173
|
+
name: "my-v2-task-id",
|
|
174
|
+
type: "task",
|
|
175
|
+
version: "V2",
|
|
176
|
+
running: 3,
|
|
177
|
+
queued: 12,
|
|
178
|
+
paused: false,
|
|
179
|
+
concurrencyLimit: null,
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### Pausing and resuming queues
|
|
184
|
+
|
|
185
|
+
You can pause a queue to prevent new runs from starting. Runs that are currently executing will continue to completion.
|
|
186
|
+
|
|
187
|
+
```ts
|
|
188
|
+
import { queues } from "@trigger.dev/sdk";
|
|
189
|
+
|
|
190
|
+
// Pause a queue using its ID
|
|
191
|
+
await queues.pause("queue_1234");
|
|
192
|
+
|
|
193
|
+
// Or using type and name
|
|
194
|
+
await queues.pause({ type: "task", name: "my-task-id" });
|
|
195
|
+
await queues.pause({ type: "custom", name: "my-custom-queue" });
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
To resume a paused queue and allow new runs to start:
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
import { queues } from "@trigger.dev/sdk";
|
|
202
|
+
|
|
203
|
+
// Resume a queue using its ID
|
|
204
|
+
await queues.resume("queue_1234");
|
|
205
|
+
|
|
206
|
+
// Or using type and name
|
|
207
|
+
await queues.resume({ type: "task", name: "my-task-id" });
|
|
208
|
+
await queues.resume({ type: "custom", name: "my-custom-queue" });
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Overriding concurrency limits
|
|
212
|
+
|
|
213
|
+
<Warning>
|
|
214
|
+
`queues.overrideConcurrencyLimit` and `queues.resetConcurrencyLimit` are deprecated and only work
|
|
215
|
+
for queues on the legacy model, where the queue carried its own concurrency limit. On the current
|
|
216
|
+
model, declare concurrency with the task `concurrency` option and manage it through
|
|
217
|
+
[`concurrencyLimits`](/concurrency), e.g. `concurrencyLimits.override("task/my-task", { total: 10 })`
|
|
218
|
+
and `concurrencyLimits.reset("task/my-task")`. A legacy limit on a queue used with
|
|
219
|
+
`concurrencyKey` maps to `perKey` rather than `total`, and a limit on a custom queue shared by
|
|
220
|
+
several tasks maps to a named limit declared with `concurrencyLimit()`, again using `perKey`
|
|
221
|
+
when the queue receives keyed runs.
|
|
222
|
+
</Warning>
|
|
223
|
+
|
|
224
|
+
You can temporarily override a queue's concurrency limit. This is useful for scaling up or down based on demand:
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
import { queues } from "@trigger.dev/sdk";
|
|
228
|
+
|
|
229
|
+
// Set concurrency limit to 5
|
|
230
|
+
await queues.overrideConcurrencyLimit("queue_1234", 5);
|
|
231
|
+
|
|
232
|
+
// Or using type and name
|
|
233
|
+
await queues.overrideConcurrencyLimit({ type: "task", name: "my-task-id" }, 20);
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
To reset the concurrency limit back to the base value defined in your code:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
import { queues } from "@trigger.dev/sdk";
|
|
240
|
+
|
|
241
|
+
// Reset concurrency limit to the base value
|
|
242
|
+
await queues.resetConcurrencyLimit("queue_1234");
|
|
243
|
+
|
|
244
|
+
// Or using type and name
|
|
245
|
+
await queues.resetConcurrencyLimit({ type: "task", name: "my-task-id" });
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
Overrides survive deploys: redeploying your code keeps an active override until you reset it.
|
package/docs/reports.mdx
CHANGED
|
@@ -148,7 +148,7 @@ An unknown report key returns `404` with the list of available keys.
|
|
|
148
148
|
<Card title="MCP tools" icon="wrench" href="/mcp-tools">
|
|
149
149
|
Every tool the MCP server exposes, including `get_report`.
|
|
150
150
|
</Card>
|
|
151
|
-
<Card title="Concurrency
|
|
151
|
+
<Card title="Concurrency" icon="layer-group" href="/concurrency">
|
|
152
152
|
Configure the concurrency limits the Flow verdict checks against.
|
|
153
153
|
</Card>
|
|
154
154
|
<Card title="Query your data" icon="magnifying-glass" href="/observability/query">
|
package/docs/runs/priority.mdx
CHANGED
|
@@ -3,29 +3,6 @@ title: "Priority"
|
|
|
3
3
|
description: "Specify a priority when triggering a run."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
import Priority from "/snippets/priority.mdx";
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
- You want runs for your premium users to take priority over free users.
|
|
10
|
-
|
|
11
|
-
The value for priority is a time offset in seconds that determines the order of dequeuing.
|
|
12
|
-
|
|
13
|
-

|
|
14
|
-
|
|
15
|
-
If you specify a priority of `10` the run will dequeue before runs that were triggered with no priority 8 seconds ago, like in this example:
|
|
16
|
-
|
|
17
|
-
```ts
|
|
18
|
-
// no priority = 0
|
|
19
|
-
await myTask.trigger({ foo: "bar" });
|
|
20
|
-
|
|
21
|
-
//... imagine 8s pass by
|
|
22
|
-
|
|
23
|
-
// this run will start before the run above that was triggered 8s ago (with no priority)
|
|
24
|
-
await myTask.trigger({ foo: "bar" }, { priority: 10 });
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
If you passed a value of `3600` the run would dequeue before runs that were triggered an hour ago (with no priority).
|
|
28
|
-
|
|
29
|
-
<Note>
|
|
30
|
-
Setting a high priority will not allow you to beat runs from other organizations. It will only affect the order of your own runs.
|
|
31
|
-
</Note>
|
|
8
|
+
<Priority />
|
|
@@ -23,6 +23,7 @@ mode: "wide"
|
|
|
23
23
|
| **Postgres** | | | |
|
|
24
24
|
| `DATABASE_URL` | Yes | — | PostgreSQL connection string. |
|
|
25
25
|
| `DIRECT_URL` | Yes | — | Direct DB connection string used for migrations etc. |
|
|
26
|
+
| `WEBHOOK_DELIVERIES_REPLICATION_DATABASE_URL` | No | `WEBHOOK_DATABASE_URL`, then `DATABASE_URL` | Direct PostgreSQL connection for webhook delivery replication to ClickHouse. Must target the database containing `WebhookDelivery` and use credentials with replication privileges. Set this when the webhook runtime connection uses a pooler. |
|
|
26
27
|
| `DATABASE_CONNECTION_LIMIT` | No | 10 | Max DB connections. |
|
|
27
28
|
| `DATABASE_POOL_TIMEOUT` | No | 60 | DB pool timeout (s). |
|
|
28
29
|
| `DATABASE_CONNECTION_TIMEOUT` | No | 20 | DB connect timeout (s). |
|
|
@@ -77,6 +78,12 @@ mode: "wide"
|
|
|
77
78
|
| `API_RATE_LIMIT_LIMITER_LOGS_ENABLED` | No | 0 | API rate limit limiter logs. |
|
|
78
79
|
| `API_RATE_LIMIT_JWT_WINDOW` | No | 1m | API rate limit JWT window. |
|
|
79
80
|
| `API_RATE_LIMIT_JWT_TOKENS` | No | 60 | API rate limit JWT tokens. |
|
|
81
|
+
| `API_RATE_LIMIT_METRICS_ENABLED` | No | 0 | Record API rate limit usage into the `metrics` table: `1` for everyone, `allowlist` for flagged organizations. |
|
|
82
|
+
| `API_RATE_LIMIT_METRICS_BUCKET_SECONDS` | No | 10 | Aggregation bucket width for API rate limit metrics: 10, 20, 30 or a multiple of 60. |
|
|
83
|
+
| `API_RATE_LIMIT_METRICS_FLUSH_INTERVAL_MS` | No | 10000 | How often aggregated API rate limit metrics are flushed to ClickHouse. |
|
|
84
|
+
| `API_RATE_LIMIT_METRICS_MAX_ENTRIES` | No | 10000 | Cap on distinct (environment, bucket) entries held between flushes. |
|
|
85
|
+
| `API_RATE_LIMIT_METRICS_WAIT_FOR_ASYNC_INSERT` | No | 0 | Wait for ClickHouse to write each async insert of API rate limit metrics, surfacing write failures. |
|
|
86
|
+
| `API_RATE_LIMIT_METRICS_INSERT_BUSY_TIMEOUT_MS` | No | 10000 | How long ClickHouse buffers API rate limit metric inserts before writing a part. |
|
|
80
87
|
| `DEPLOYMENT_RATE_LIMIT_REFILL_INTERVAL` | No | 10s | Deployment endpoints rate limit refill interval. |
|
|
81
88
|
| `DEPLOYMENT_RATE_LIMIT_MAX` | No | 1500 | Deployment endpoints rate limit max. |
|
|
82
89
|
| `DEPLOYMENT_RATE_LIMIT_REFILL_RATE` | No | 500 | Deployment endpoints rate limit refill rate. |
|