@trigger.dev/sdk 4.6.4 → 4.7.0

package/docs/github-actions.mdx

@@ -85,7 +85,7 @@ If you already have a GitHub action file, you can just add the final step "🚀
 
 ### Pinning runs to the deployment you just built
 
-The `--external-id ${{ github.sha }}` above tags the deployment with the commit it was built from. That is the first half of [version skew protection](/deployment/version-skew-protection): to complete it, give your running application the **same value** so it sends that id when it triggers.
+The `--external-id ${{ github.sha }}` above tags the deployment with the commit it was built from. That is the first half of [version skew protection](/deployment/atomic-deployment): to complete it, give your running application the **same value** so it sends that id when it triggers.
 
 ```bash
 # In your application's runtime environment, for the release built from this commit
@@ -104,7 +104,7 @@ Every task triggered by that release is then pinned to the deployment built from
   `paths:` filter to this workflow, `${{ github.sha }}` stops being a safe id: commits that don't
   touch your tasks never produce a deployment carrying that SHA, so every run from those releases
   expires. See [when nothing ever
-  lands](/deployment/version-skew-protection#when-nothing-ever-lands).
+  lands](/deployment/atomic-deployment#when-nothing-ever-lands).
 </Note>
 
 ## Preview branches

package/docs/github-integration.mdx

@@ -74,7 +74,7 @@ The name of the preview branch matches the branch name of the pull request.
 
 ## Version skew protection
 
-Every deployment the GitHub integration creates is tagged with the commit SHA it was built from. That is the deploy half of [version skew protection](/deployment/version-skew-protection) — you get it for free.
+Every deployment the GitHub integration creates is tagged with the commit SHA it was built from. That is the deploy half of [version skew protection](/deployment/atomic-deployment) — you get it for free.
 
 To complete it, give your running application the same value. Unlike the Vercel integration, we have no access to wherever your app is hosted, so this half is yours to set:
 
@@ -82,7 +82,7 @@ To complete it, give your running application the same value. Unlike the Vercel
 TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-commit-sha-this-release-was-built-from>
 ```
 
-If your host already exposes the commit SHA at runtime, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1` instead and the SDK will find it — see the [platform table](/deployment/version-skew-protection#hosting-platforms).
+If your host already exposes the commit SHA at runtime, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1` instead and the SDK will find it — see the [platform table](/deployment/atomic-deployment#hosting-platforms).
 
 ## Disconnecting a repository
 

package/docs/idempotency.mdx

@@ -3,7 +3,9 @@ title: "Idempotency"
 description: "An API call or operation is idempotent if it has the same result when called more than once."
 ---
 
-We currently support idempotency at the task level, meaning that if you trigger a task with the same `idempotencyKey` twice, the second request will not create a new task run. Instead, the original run's handle is returned, allowing you to track the existing run's progress.
+**Idempotency keys deduplicate task triggers.** If you trigger a task with the same `idempotencyKey` twice, the second request does not create a new run. It returns the original run's handle, so you can track the existing run's progress.
+
+The key applies to the trigger call and nothing else. It deduplicates `trigger()`, `triggerAndWait()`, and `batchTrigger()`; it does not make the code inside a task's `run()` function idempotent. See [Side effects inside `run()`](#side-effects-inside-run) for what that means when a task calls an external API.
 
 ## Why use idempotency keys?
 
@@ -31,10 +33,46 @@ sequenceDiagram
 
 Other common use cases include:
 
-- **Preventing duplicate emails** - Ensure a confirmation email is only sent once, even if the parent task retries
-- **Avoiding double-charging customers** - Prevent duplicate payment processing during retries
-- **One-time setup tasks** - Ensure initialization or migration tasks only run once
-- **Deduplicating webhook processing** - Handle the same webhook event only once, even if it's delivered multiple times
+- **Preventing duplicate emails** - Trigger the email task once, even if the parent task retries
+- **Avoiding double-charging customers** - Trigger the payment task once, even if the parent task retries. The payment API call itself still needs the provider's own idempotency key, see [Side effects inside `run()`](#side-effects-inside-run)
+- **One-time setup tasks** - Trigger initialization or migration tasks once
+- **Deduplicating webhook processing** - Trigger the handler task once per webhook event, even if the event is delivered multiple times
+
+## Side effects inside `run()`
+
+An idempotency key stops a task from being *triggered* twice. It does not stop the code inside that task from *running* twice. When a run retries, `run()` executes again from the top, and every API call, database write, or email inside it happens again unless that operation is itself idempotent.
+
+This matters most for payments. A refund issued directly inside a retryable task is issued again on every retry, even when the retry is caused by an unrelated failure later in the same function. Moving the refund into a child task and triggering it with an idempotency key does not close the gap either: the child is triggered once, but its own `run()` can retry after the provider has accepted the request. Only the provider can deduplicate its own API call.
+
+Pass the provider's idempotency key on every call that must happen at most once. Derive it from a value that stays the same across every attempt of the run. The run ID, `ctx.run.id`, always qualifies: retries are attempts of the same run, so the ID does not change between them. This is the same value the default `run` scope mixes into a Trigger.dev idempotency key.
+
+```ts /trigger/refund-order.ts
+import { idempotencyKeys, task } from "@trigger.dev/sdk";
+import Stripe from "stripe";
+import { sendRefundEmail } from "./send-refund-email";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export const refundOrder = task({
+  id: "refund-order",
+  retry: { maxAttempts: 3 },
+  run: async (payload: { orderId: string; paymentIntentId: string; amount: number }, { ctx }) => {
+    // The run ID is stable across retries, so Stripe returns the original refund instead of creating a second one
+    await stripe.refunds.create(
+      { payment_intent: payload.paymentIntentId, amount: payload.amount },
+      { idempotencyKey: `refund-${ctx.run.id}` }
+    );
+
+    // The Trigger.dev key is run-scoped by default, so a retry does not create a second email run
+    const idempotencyKey = await idempotencyKeys.create("refund-email");
+    await sendRefundEmail.trigger({ orderId: payload.orderId }, { idempotencyKey });
+  },
+});
+```
+
+The run ID protects against retries of one run. If the same task can be triggered more than once for the same order, either trigger it with a Trigger.dev idempotency key so repeated triggers resolve to the same run and the same run ID, or key the provider call on a business ID from your payload instead, such as `refund-${payload.orderId}`, which deduplicates across separate runs too.
+
+Use a Trigger.dev idempotency key to stop a retry triggering a task twice, and the provider's idempotency key to stop a retry calling the provider twice. For a side effect with no idempotency support, record that you performed it in your own database and check that record before performing it again.
 
 ## `idempotencyKey` option
 

package/docs/introduction.mdx

@@ -51,7 +51,7 @@ Build durable, multi-turn agents with the [chat agent](/ai-chat/overview): one l
 
 ## Scale and scheduling
 
-Set how many runs of a task execute at once, globally or per tenant, with [queues and concurrency](/queue-concurrency). 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).
+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).
 
 ## Self-hosting
 

package/docs/limits.mdx

@@ -14,11 +14,15 @@ You can view your current limits, quotas, and rate limit usage in real-time by v
 
 ## Concurrency limits
 
-| Pricing tier | Limit                |
-| :----------- | :------------------- |
-| Free         | 10 concurrent runs   |
-| Hobby        | 25 concurrent runs   |
-| Pro          | 100+ concurrent runs |
+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:
+
+| Pricing tier | Production | Staging | Preview | Development |
+| :----------- | :--------- | :------ | :------ | :---------- |
+| Free         | 20         | 10      | 10      | 25          |
+| Hobby        | 50         | 25      | 25      | 25          |
+| Pro          | 200+       | 100     | 100     | 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.
 
 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.
 
@@ -50,7 +54,13 @@ The maximum number of runs that can be queued **per queue** (not across all queu
 
 ## Maximum run TTL
 
-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).
+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.
+
+**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.
+
+There is no maximum on `delay`.
+
+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).
 
 ## Schedules
 

package/docs/observability/query.mdx

@@ -28,6 +28,31 @@ description: "Query allows you to write custom queries against your data using T
 
 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).
 
+#### API rate limit metrics
+
+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:
+
+- `api.rate_limit.allowed` (`sum`): requests that passed the rate limiter
+- `api.rate_limit.denied` (`sum`): requests rejected with a 429
+- `api.rate_limit.remaining_min` (`gauge`): the lowest remaining token count seen in the bucket
+- `api.rate_limit.limit.per_second` (`gauge`): the sustained rate your limit refills at, in requests per second
+- `api.rate_limit.limit.burst` (`gauge`): the most requests the limit admits at once
+
+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.
+
+```sql
+SELECT
+  toStartOfMinute(bucket_start) AS minute,
+  sumIf(metric_value, metric_name IN ('api.rate_limit.allowed', 'api.rate_limit.denied')) AS attempts,
+  sumIf(metric_value, metric_name = 'api.rate_limit.denied') AS denied,
+  maxIf(metric_value, metric_name = 'api.rate_limit.limit.per_second') * 60 AS limit_per_minute
+FROM metrics
+WHERE metric_name LIKE 'api.rate_limit.%'
+GROUP BY minute
+ORDER BY minute
+LIMIT 1000
+```
+
 ### `prettyFormat()`
 
 Use `prettyFormat()` to format metric values for display:

package/docs/queues.mdx

@@ -0,0 +1,271 @@
+---
+title: "Queues"
+description: "Control the order your runs execute in."
+---
+
+import Priority from "/snippets/priority.mdx";
+
+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.
+
+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.
+
+## Sharing a queue between tasks
+
+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:
+
+```ts /trigger/emails.ts
+import { queue, task } from "@trigger.dev/sdk";
+
+const emailQueue = queue({ name: "emails" });
+
+export const sendWelcomeEmail = task({
+  id: "send-welcome-email",
+  queue: emailQueue,
+  run: async (payload) => {
+    //...
+  },
+});
+
+export const sendDigestEmail = task({
+  id: "send-digest-email",
+  queue: emailQueue,
+  run: async (payload) => {
+    //...
+  },
+});
+```
+
+<Note>
+  If what you want to share is a concurrency cap rather than ordering, you don't need a shared
+  queue: declare a named limit with `concurrencyLimit()` and each task keeps its own queue while
+  drawing from the shared limit. See [sharing a limit between
+  tasks](/concurrency#sharing-a-limit-between-tasks).
+</Note>
+
+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.
+
+## Setting the queue when you trigger a run
+
+When you trigger a task you can override its queue by name. This is really useful if you sometimes have high priority runs:
+
+```ts /trigger/override-queue.ts
+import { queue, task } from "@trigger.dev/sdk";
+
+const paidQueue = queue({ name: "paid-users" });
+
+export const generatePullRequest = task({
+  id: "generate-pull-request",
+  // normally this task is limited to 1 run at a time
+  concurrency: { total: 1 },
+  run: async (payload) => {
+    //todo generate a PR using OpenAI
+  },
+});
+```
+
+Triggering from your backend and overriding the queue:
+
+```ts app/api/push/route.ts
+import { generatePullRequest } from "~/trigger/override-queue";
+
+export async function POST(request: Request) {
+  const data = await request.json();
+
+  if (data.branch === "main") {
+    //trigger the task, with the paid users queue
+    const handle = await generatePullRequest.trigger(data, {
+      // Set the paid users queue
+      queue: "paid-users",
+    });
+
+    return Response.json(handle);
+  } else {
+    //triggered with the default queue
+    const handle = await generatePullRequest.trigger(data);
+    return Response.json(handle);
+  }
+}
+```
+
+## Priority
+
+You can re-order runs within a queue at trigger time by giving them a priority:
+
+<Priority />
+
+## Archiving queues
+
+Queues are created when you deploy, so renaming a queue or deleting a task leaves its old queue behind. To tidy up the list, open the queue's menu on the Concurrency page in the dashboard and choose **Archive**.
+
+Archiving only hides the queue in the dashboard, and it doesn't affect runs. Archived queues don't count towards the **Allocated** total, even if they have runs. To see them, turn on the **Show archived** toggle; to bring one back, choose **Unarchive** from its menu.
+
+- You can only archive a queue that your current deployment no longer declares.
+- You can't archive a queue while it has runs waiting or in progress, or while it's paused or its concurrency limit or [`total` limit](/concurrency) is 0.
+- If an archived queue gets new runs, it stays hidden, but a warning above the list names it until it's empty.
+- Pausing an archived queue, or setting its concurrency limit or `total` limit to 0 (including by resetting an override), unarchives it.
+- If a later deploy declares the queue again, it's unarchived automatically.
+- The SDK and API still list archived queues.
+
+<Note>
+  Some runs belong to a queue without currently sitting in it, so they don't count as activity:
+  delayed runs that haven't reached their start time yet, runs waiting for a deploy of their
+  version, runs that are waiting (for example on `wait.for` or a child task) or have been
+  checkpointed, and, depending on how the engine is configured, runs with a concurrency key that
+  have been handed to a worker but not picked up yet. A queue with only runs like these can be
+  archived, and the warning won't name it until one of them is back in the queue or running. These
+  runs still execute normally and always show on the Runs page.
+</Note>
+
+## Managing queues with the SDK
+
+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.
+
+<Note>
+  Import from `@trigger.dev/sdk`:
+  ```ts
+  import { queues } from "@trigger.dev/sdk";
+  ```
+</Note>
+
+### Listing queues
+
+You can list all queues in your environment with pagination support:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// List all queues (returns paginated results)
+const allQueues = await queues.list();
+
+// With pagination options
+const pagedQueues = await queues.list({
+  page: 1,
+  perPage: 20,
+});
+```
+
+### Retrieving a queue
+
+You can retrieve a specific queue by its ID, or by its type and name:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Using queue ID (starts with "queue_")
+const queueById = await queues.retrieve("queue_1234");
+
+// Using type and name for a task's default queue
+const taskQueue = await queues.retrieve({
+  type: "task",
+  name: "my-task-id",
+});
+
+// Using type and name for a custom queue
+const customQueue = await queues.retrieve({
+  type: "custom",
+  name: "my-custom-queue",
+});
+```
+
+The queue object contains useful information about the queue state, and its `version` discriminates the shape:
+
+```ts
+// V1: the queue carries its own concurrency limit and override state
+{
+  id: "queue_1234",       // Queue ID
+  name: "my-task-id",     // Queue name
+  type: "task",           // "task" or "custom"
+  version: "V1",
+  running: 5,             // Currently executing runs
+  queued: 10,             // Runs waiting to execute
+  paused: false,          // Whether the queue is paused
+  concurrencyLimit: 10,   // The queue's own limit
+  concurrency: {
+    current: 10,          // Effective limit
+    base: 10,             // Default limit from code
+    override: null,       // Override value (if set)
+    overriddenAt: null,   // When override was applied
+    overriddenBy: null,   // Who applied the override
+  }
+}
+
+// V2: the queue is only the line runs wait in. Concurrency is declared with
+// the task `concurrency` option and managed through `concurrencyLimits`.
+{
+  id: "queue_5678",
+  name: "my-v2-task-id",
+  type: "task",
+  version: "V2",
+  running: 3,
+  queued: 12,
+  paused: false,
+  concurrencyLimit: null,
+}
+```
+
+### Pausing and resuming queues
+
+You can pause a queue to prevent new runs from starting. Runs that are currently executing will continue to completion.
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Pause a queue using its ID
+await queues.pause("queue_1234");
+
+// Or using type and name
+await queues.pause({ type: "task", name: "my-task-id" });
+await queues.pause({ type: "custom", name: "my-custom-queue" });
+```
+
+To resume a paused queue and allow new runs to start:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Resume a queue using its ID
+await queues.resume("queue_1234");
+
+// Or using type and name
+await queues.resume({ type: "task", name: "my-task-id" });
+await queues.resume({ type: "custom", name: "my-custom-queue" });
+```
+
+### Overriding concurrency limits
+
+<Warning>
+  `queues.overrideConcurrencyLimit` and `queues.resetConcurrencyLimit` are deprecated and only work
+  for queues on the legacy model, where the queue carried its own concurrency limit. On the current
+  model, declare concurrency with the task `concurrency` option and manage it through
+  [`concurrencyLimits`](/concurrency), e.g. `concurrencyLimits.override("task/my-task", { total: 10 })`
+  and `concurrencyLimits.reset("task/my-task")`. A legacy limit on a queue used with
+  `concurrencyKey` maps to `perKey` rather than `total`, and a limit on a custom queue shared by
+  several tasks maps to a named limit declared with `concurrencyLimit()`, again using `perKey`
+  when the queue receives keyed runs.
+</Warning>
+
+You can temporarily override a queue's concurrency limit. This is useful for scaling up or down based on demand:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Set concurrency limit to 5
+await queues.overrideConcurrencyLimit("queue_1234", 5);
+
+// Or using type and name
+await queues.overrideConcurrencyLimit({ type: "task", name: "my-task-id" }, 20);
+```
+
+To reset the concurrency limit back to the base value defined in your code:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Reset concurrency limit to the base value
+await queues.resetConcurrencyLimit("queue_1234");
+
+// Or using type and name
+await queues.resetConcurrencyLimit({ type: "task", name: "my-task-id" });
+```
+
+Overrides survive deploys: redeploying your code keeps an active override until you reset it.

package/docs/reports.mdx

@@ -148,7 +148,7 @@ An unknown report key returns `404` with the list of available keys.
   <Card title="MCP tools" icon="wrench" href="/mcp-tools">
     Every tool the MCP server exposes, including `get_report`.
   </Card>
-  <Card title="Concurrency & queues" icon="layer-group" href="/queue-concurrency">
+  <Card title="Concurrency" icon="layer-group" href="/concurrency">
     Configure the concurrency limits the Flow verdict checks against.
   </Card>
   <Card title="Query your data" icon="magnifying-glass" href="/observability/query">

package/docs/runs/priority.mdx

@@ -3,29 +3,6 @@ title: "Priority"
 description: "Specify a priority when triggering a run."
 ---
 
-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:
+import Priority from "/snippets/priority.mdx";
 
-- You have critical work that needs to start more quickly (and you have long queues).
-- You want runs for your premium users to take priority over free users.
-
-The value for priority is a time offset in seconds that determines the order of dequeuing.
-
-![Priority runs](/images/priority-runs.png)
-
-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:
-
-```ts
-// no priority = 0
-await myTask.trigger({ foo: "bar" });
-
-//... imagine 8s pass by
-
-// this run will start before the run above that was triggered 8s ago (with no priority)
-await myTask.trigger({ foo: "bar" }, { priority: 10 });
-```
-
-If you passed a value of `3600` the run would dequeue before runs that were triggered an hour ago (with no priority).
-
-<Note>
-  Setting a high priority will not allow you to beat runs from other organizations. It will only affect the order of your own runs.
-</Note>
+<Priority />

package/docs/self-hosting/env/webapp.mdx

@@ -23,6 +23,7 @@ mode: "wide"
 | **Postgres**                                     |          |                       |                                                                                                                    |
 | `DATABASE_URL`                                   | Yes      | —                     | PostgreSQL connection string.                                                                                      |
 | `DIRECT_URL`                                     | Yes      | —                     | Direct DB connection string used for migrations etc.                                                               |
+| `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. |
 | `DATABASE_CONNECTION_LIMIT`                      | No       | 10                    | Max DB connections.                                                                                                |
 | `DATABASE_POOL_TIMEOUT`                          | No       | 60                    | DB pool timeout (s).                                                                                               |
 | `DATABASE_CONNECTION_TIMEOUT`                    | No       | 20                    | DB connect timeout (s).                                                                                            |
@@ -77,6 +78,12 @@ mode: "wide"
 | `API_RATE_LIMIT_LIMITER_LOGS_ENABLED`            | No       | 0                     | API rate limit limiter logs.                                                                                       |
 | `API_RATE_LIMIT_JWT_WINDOW`                      | No       | 1m                    | API rate limit JWT window.                                                                                         |
 | `API_RATE_LIMIT_JWT_TOKENS`                      | No       | 60                    | API rate limit JWT tokens.                                                                                         |
+| `API_RATE_LIMIT_METRICS_ENABLED`                 | No       | 0                     | Record API rate limit usage into the `metrics` table: `1` for everyone, `allowlist` for flagged organizations.     |
+| `API_RATE_LIMIT_METRICS_BUCKET_SECONDS`          | No       | 10                    | Aggregation bucket width for API rate limit metrics: 10, 20, 30 or a multiple of 60.                               |
+| `API_RATE_LIMIT_METRICS_FLUSH_INTERVAL_MS`       | No       | 10000                 | How often aggregated API rate limit metrics are flushed to ClickHouse.                                             |
+| `API_RATE_LIMIT_METRICS_MAX_ENTRIES`             | No       | 10000                 | Cap on distinct (environment, bucket) entries held between flushes.                                                |
+| `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.                |
+| `API_RATE_LIMIT_METRICS_INSERT_BUSY_TIMEOUT_MS`  | No       | 10000                 | How long ClickHouse buffers API rate limit metric inserts before writing a part.                                   |
 | `DEPLOYMENT_RATE_LIMIT_REFILL_INTERVAL`          | No       | 10s                   | Deployment endpoints rate limit refill interval.                                                                   |
 | `DEPLOYMENT_RATE_LIMIT_MAX`                      | No       | 1500                  | Deployment endpoints rate limit max.                                                                               |
 | `DEPLOYMENT_RATE_LIMIT_REFILL_RATE`              | No       | 500                   | Deployment endpoints rate limit refill rate.                                                                       |

package/docs/tasks/overview.mdx

@@ -98,16 +98,14 @@ For more information read [the retrying guide](/errors-retrying).
 
 It's also worth mentioning that you can [retry a block of code](/errors-retrying) inside your tasks as well.
 
-### `queue` options
+### `queue` and `concurrency` options
 
-Queues allow you to control the concurrency of your tasks. This allows you to have one-at-a-time execution and parallel executions. There are also more advanced techniques like having different concurrencies for different sets of your users. For more information read [the concurrency & queues guide](/queue-concurrency).
+Queues control the order your runs execute in, and concurrency limits control how many execute at once: one-at-a-time execution, parallel executions, and more advanced techniques like separate concurrency for different sets of your users. For more information read the [Queues](/queues) and [Concurrency](/concurrency) guides.
 
 ```ts /trigger/one-at-a-time.ts
 export const oneAtATime = task({
   id: "one-at-a-time",
-  queue: {
-    concurrencyLimit: 1,
-  },
+  concurrency: { total: 1 },
   run: async (payload: any, { ctx }) => {
     //...
   },