@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.
Files changed (124) hide show
  1. package/dist/commonjs/v3/ai.d.ts +37 -12
  2. package/dist/commonjs/v3/ai.js +349 -278
  3. package/dist/commonjs/v3/ai.js.map +1 -1
  4. package/dist/commonjs/v3/auth.js +8 -2
  5. package/dist/commonjs/v3/auth.js.map +1 -1
  6. package/dist/commonjs/v3/chat-client.js +7 -0
  7. package/dist/commonjs/v3/chat-client.js.map +1 -1
  8. package/dist/commonjs/v3/chat-server.d.ts +1 -0
  9. package/dist/commonjs/v3/chat-server.js +8 -0
  10. package/dist/commonjs/v3/chat-server.js.map +1 -1
  11. package/dist/commonjs/v3/chat.js +13 -9
  12. package/dist/commonjs/v3/chat.js.map +1 -1
  13. package/dist/commonjs/v3/compactionResponse.d.ts +9 -0
  14. package/dist/commonjs/v3/compactionResponse.js +37 -0
  15. package/dist/commonjs/v3/compactionResponse.js.map +1 -0
  16. package/dist/commonjs/v3/concurrency-shared.d.ts +13 -0
  17. package/dist/commonjs/v3/concurrency-shared.js +35 -0
  18. package/dist/commonjs/v3/concurrency-shared.js.map +1 -0
  19. package/dist/commonjs/v3/concurrencyLimits.d.ts +73 -0
  20. package/dist/commonjs/v3/concurrencyLimits.js +166 -0
  21. package/dist/commonjs/v3/concurrencyLimits.js.map +1 -0
  22. package/dist/commonjs/v3/index.d.ts +2 -1
  23. package/dist/commonjs/v3/index.js +3 -1
  24. package/dist/commonjs/v3/index.js.map +1 -1
  25. package/dist/commonjs/v3/managedChatResponse.d.ts +44 -0
  26. package/dist/commonjs/v3/managedChatResponse.js +233 -0
  27. package/dist/commonjs/v3/managedChatResponse.js.map +1 -0
  28. package/dist/commonjs/v3/queues.d.ts +31 -0
  29. package/dist/commonjs/v3/queues.js +31 -0
  30. package/dist/commonjs/v3/queues.js.map +1 -1
  31. package/dist/commonjs/v3/runs.d.ts +5 -0
  32. package/dist/commonjs/v3/sessionTracing.d.ts +7 -0
  33. package/dist/commonjs/v3/sessionTracing.js +44 -0
  34. package/dist/commonjs/v3/sessionTracing.js.map +1 -0
  35. package/dist/commonjs/v3/sessions.js +31 -34
  36. package/dist/commonjs/v3/sessions.js.map +1 -1
  37. package/dist/commonjs/v3/shared.d.ts +18 -1
  38. package/dist/commonjs/v3/shared.js +145 -52
  39. package/dist/commonjs/v3/shared.js.map +1 -1
  40. package/dist/commonjs/v3/steeringContext.d.ts +41 -0
  41. package/dist/commonjs/v3/steeringContext.js +118 -0
  42. package/dist/commonjs/v3/steeringContext.js.map +1 -0
  43. package/dist/commonjs/v3/transcriptStorage.d.ts +4 -1
  44. package/dist/commonjs/v3/transcriptStorage.js +55 -4
  45. package/dist/commonjs/v3/transcriptStorage.js.map +1 -1
  46. package/dist/commonjs/version.js +1 -1
  47. package/dist/esm/v3/ai.d.ts +37 -12
  48. package/dist/esm/v3/ai.js +350 -279
  49. package/dist/esm/v3/ai.js.map +1 -1
  50. package/dist/esm/v3/auth.js +8 -2
  51. package/dist/esm/v3/auth.js.map +1 -1
  52. package/dist/esm/v3/chat-client.js +7 -0
  53. package/dist/esm/v3/chat-client.js.map +1 -1
  54. package/dist/esm/v3/chat-server.d.ts +1 -0
  55. package/dist/esm/v3/chat-server.js +8 -0
  56. package/dist/esm/v3/chat-server.js.map +1 -1
  57. package/dist/esm/v3/chat.js +13 -9
  58. package/dist/esm/v3/chat.js.map +1 -1
  59. package/dist/esm/v3/compactionResponse.d.ts +9 -0
  60. package/dist/esm/v3/compactionResponse.js +34 -0
  61. package/dist/esm/v3/compactionResponse.js.map +1 -0
  62. package/dist/esm/v3/concurrency-shared.d.ts +13 -0
  63. package/dist/esm/v3/concurrency-shared.js +31 -0
  64. package/dist/esm/v3/concurrency-shared.js.map +1 -0
  65. package/dist/esm/v3/concurrencyLimits.d.ts +73 -0
  66. package/dist/esm/v3/concurrencyLimits.js +158 -0
  67. package/dist/esm/v3/concurrencyLimits.js.map +1 -0
  68. package/dist/esm/v3/index.d.ts +2 -1
  69. package/dist/esm/v3/index.js +2 -1
  70. package/dist/esm/v3/index.js.map +1 -1
  71. package/dist/esm/v3/managedChatResponse.d.ts +44 -0
  72. package/dist/esm/v3/managedChatResponse.js +228 -0
  73. package/dist/esm/v3/managedChatResponse.js.map +1 -0
  74. package/dist/esm/v3/queues.d.ts +31 -0
  75. package/dist/esm/v3/queues.js +31 -0
  76. package/dist/esm/v3/queues.js.map +1 -1
  77. package/dist/esm/v3/runs.d.ts +5 -0
  78. package/dist/esm/v3/sessionTracing.d.ts +7 -0
  79. package/dist/esm/v3/sessionTracing.js +40 -0
  80. package/dist/esm/v3/sessionTracing.js.map +1 -0
  81. package/dist/esm/v3/sessions.js +31 -34
  82. package/dist/esm/v3/sessions.js.map +1 -1
  83. package/dist/esm/v3/shared.d.ts +18 -1
  84. package/dist/esm/v3/shared.js +145 -53
  85. package/dist/esm/v3/shared.js.map +1 -1
  86. package/dist/esm/v3/steeringContext.d.ts +41 -0
  87. package/dist/esm/v3/steeringContext.js +113 -0
  88. package/dist/esm/v3/steeringContext.js.map +1 -0
  89. package/dist/esm/v3/transcriptStorage.d.ts +4 -1
  90. package/dist/esm/v3/transcriptStorage.js +55 -5
  91. package/dist/esm/v3/transcriptStorage.js.map +1 -1
  92. package/dist/esm/version.js +1 -1
  93. package/docs/ai-chat/anatomy.mdx +44 -24
  94. package/docs/ai-chat/client-protocol.mdx +2 -0
  95. package/docs/ai-chat/error-handling.mdx +44 -76
  96. package/docs/ai-chat/frontend.mdx +27 -21
  97. package/docs/ai-chat/lifecycle-hooks.mdx +4 -2
  98. package/docs/ai-chat/patterns/branching-conversations.mdx +95 -230
  99. package/docs/ai-chat/patterns/human-in-the-loop.mdx +166 -164
  100. package/docs/ai-chat/patterns/tool-result-auditing.mdx +28 -27
  101. package/docs/ai-chat/pending-messages.mdx +19 -5
  102. package/docs/ai-chat/quick-start.mdx +26 -20
  103. package/docs/ai-chat/reference.mdx +4 -2
  104. package/docs/ai-chat/testing.mdx +16 -4
  105. package/docs/cli-env-commands.mdx +114 -0
  106. package/docs/cli-projects-commands.mdx +62 -0
  107. package/docs/cli-runs-commands.mdx +94 -0
  108. package/docs/concurrency.mdx +384 -0
  109. package/docs/database-connections.mdx +3 -3
  110. package/docs/deploy-environment-variables.mdx +6 -0
  111. package/docs/idempotency.mdx +43 -5
  112. package/docs/introduction.mdx +58 -152
  113. package/docs/limits.mdx +16 -6
  114. package/docs/observability/query.mdx +25 -0
  115. package/docs/queues.mdx +248 -0
  116. package/docs/reports.mdx +1 -1
  117. package/docs/runs/priority.mdx +2 -25
  118. package/docs/self-hosting/env/webapp.mdx +7 -0
  119. package/docs/tasks/overview.mdx +3 -5
  120. package/docs/troubleshooting-alerts.mdx +124 -1
  121. package/docs/troubleshooting.mdx +12 -0
  122. package/docs/writing-tasks-introduction.mdx +2 -1
  123. package/package.json +2 -2
  124. package/docs/queue-concurrency.mdx +0 -358
@@ -1,181 +1,69 @@
1
1
  ---
2
- title: "Welcome to the Trigger.dev docs"
2
+ title: "Trigger.dev docs"
3
3
  sidebarTitle: "Introduction"
4
- description: "Find all the resources and guides you need to get started"
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" img="/images/intro-quickstart.jpg" href="/quick-start">
10
- Get started with Trigger.dev and run your first task in 3 minutes
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
- title="Guides, frameworks & examples"
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="Building with AI" img="/images/intro-ai.jpg" href="/building-with-ai">
20
- Learn how to build Trigger.dev projects using AI coding assistants
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="Video walkthrough" img="/images/intro-video.jpg" href="/video-walkthrough">
23
- Watch an end-to-end demo of Trigger.dev in 10 minutes
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 an open source background jobs framework that lets you write reliable workflows in plain async code. Run long-running AI tasks, handle complex background jobs, and build AI agents with built-in queuing, automatic retries, and real-time monitoring. No timeouts, elastic scaling, and zero infrastructure management required.
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
- We provide everything you need to build and manage background tasks: a CLI and SDK for writing tasks in your existing codebase, support for both [regular](/tasks/overview) and [scheduled](/tasks/scheduled) tasks, full observability through our dashboard, and a [Realtime API](/realtime) with [React hooks](/realtime/react-hooks#realtime-hooks) for showing task status in your frontend. You can use [Trigger.dev Cloud](https://cloud.trigger.dev) or [self-host](/self-hosting/overview) on your own infrastructure.
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
- ## Learn the concepts
31
+ ## Core concepts
34
32
 
35
33
  <CardGroup cols={2}>
36
- <Card title="Writing tasks" icon="wand-magic-sparkles" href="/tasks/overview" color="#3B82F6">
37
- Tasks are the core of Trigger.dev. Learn what they are and how to write them.
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="#fbbf24">
40
- Learn how to trigger tasks from your codebase.
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="person-running" href="/runs" color="#EA189E">
43
- Runs are the instances of tasks that are executed. Learn how they work.
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="API keys" icon="key" href="/apikeys" color="#EAEA08">
46
- API keys are used to authenticate requests to the Trigger.dev API. Learn how to create and use
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
- ## Explore by feature
48
+ ## Build with agents
52
49
 
53
- <CardGroup>
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
- ## Explore by build extension
91
-
92
- | Extension | What it does | Docs |
93
- | :-------------------- | :----------------------------------------------------------- | :----------------------------------------------------- |
94
- | prismaExtension | Use Prisma with Trigger.dev | [prismaExtension docs](/config/extensions/prismaExtension) |
95
- | pythonExtension | Execute Python scripts in Trigger.dev | [pythonExtension docs](/config/extensions/pythonExtension) |
96
- | playwright | Use Playwright with Trigger.dev | [playwright extension docs](/config/extensions/playwright) |
97
- | puppeteer | Use Puppeteer with Trigger.dev | [puppeteer extension docs](/config/extensions/puppeteer) |
98
- | lightpanda | Use Lightpanda with Trigger.dev | [lightpanda extension docs](/config/extensions/lightpanda) |
99
- | ffmpeg | Use FFmpeg with Trigger.dev | [ffmpeg extension docs](/config/extensions/ffmpeg) |
100
- | aptGet | Install system packages with aptGet | [aptGet extension docs](/config/extensions/aptGet) |
101
- | additionalFiles | Copy additional files to the build directory | [additionalFiles docs](/config/extensions/additionalFiles) |
102
- | additionalPackages | Include additional packages in the build | [additionalPackages docs](/config/extensions/additionalPackages) |
103
- | syncEnvVars | Automatically sync environment variables to Trigger.dev | [syncEnvVars docs](/config/extensions/syncEnvVars) |
104
- | esbuildPlugin | Add existing or custom esbuild plugins to your build process | [esbuildPlugin docs](/config/extensions/esbuildPlugin) |
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
- | Pricing tier | Limit |
18
- | :----------- | :------------------- |
19
- | Free | 10 concurrent runs |
20
- | Hobby | 25 concurrent runs |
21
- | Pro | 100+ concurrent runs |
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. 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).
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:
@@ -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 & queues" icon="layer-group" href="/queue-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">
@@ -3,29 +3,6 @@ title: "Priority"
3
3
  description: "Specify a priority when triggering a run."
4
4
  ---
5
5
 
6
- You can set a priority when you trigger a run. This allows you to prioritize some of your runs over others, so they are started sooner. This is very useful when:
6
+ import Priority from "/snippets/priority.mdx";
7
7
 
8
- - You have critical work that needs to start more quickly (and you have long queues).
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
- ![Priority runs](/images/priority-runs.png)
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. |