docs(platform): Add cloud data worker capacity enforcement documentation

docs/platform/cloud/managing-airbyte-cloud/configuring-connections.md

@@ -63,6 +63,7 @@ You can configure the following settings:
 | [Destination Namespace](../../using-airbyte/core-concepts/namespaces)               | Determines where the replicated data is written to in the destination          |
 | [Destination Stream Prefix](../../using-airbyte/configuring-schema)                   | (Optional) Adds a prefix to each table name in the destination                  |
 | [Detect and propagate schema changes](../../using-airbyte/schema-change-management) | Set how Airbyte handles schema changes in the source                           |
+| Use on-demand capacity (Cloud Pro and Enterprise Flex only)                               | When enabled, syncs always run even if committed capacity is exhausted. Syncs that run when committed data worker capacity is exhausted will be charged a premium rate. Only organization admins and workspace admins can change this toggle. It also appears during connection creation. See [Monitor data worker usage](./manage-data-workers.md). |
 
 ## Stream Settings
 

docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md

@@ -26,6 +26,11 @@ You configure notifications for each workspace separately. Once you do, Airbyte
 | **Sync Disabled - Repeated Failures**   | ✓ | ✓     | Airbyte has turned off a connection due to repeated failures. It has failed 30 times consecutively and has not been successful in the last 7 days.     |
 | **Warning - Upgrade Required**          | ✓ |              | A new connector version is available, but you need to manually upgrade.                                                                                |
 | **Sync Disabled - Upgrade Required**    | ✓ |              | Airbyte turned off one or more connections automatically because you missed the deadline to upgrade the connector.                                     |
+| **Queued syncs**                        | ✓ |              | A sync from any of your connections is queued due to capacity limits. Off by default. See [Monitor data worker usage](./manage-data-workers.md).      |
+
+:::note
+"Queued syncs" notifications default to off because capacity enforcement queuing is expected behavior for most organizations. Enable this notification if you want awareness when syncs are waiting for capacity.
+:::
 
 ### Enabling schema update notifications
 
@@ -190,6 +195,12 @@ Webhook doesn't contain payload and only works for Slack notifications.
 
 Webhook doesn't contain payload and only works for Slack notifications.
 
+</details>
+<details>
+  <summary>Queued syncs</summary>
+
+Queued syncs notifications support both email and webhook. No example payload is available at this time.
+
 </details>
 
 ### Configure Slack notifications

docs/platform/cloud/managing-airbyte-cloud/manage-data-workers.md

@@ -4,7 +4,7 @@ products: cloud-plus
 
 # Monitor data worker usage
 
-If you are on a capacity-based plan, you can monitor your data worker usage across your organization. To view data worker usage, you need the **organization admin** role.
+If you are on a capacity-based plan, you can monitor your data worker usage across your organization and understand how capacity enforcement affects your syncs. When all committed data workers are in use, newly triggered sync jobs are queued until capacity becomes available. To view data worker usage, you need the **organization admin** role.
 
 ## Open the usage chart
 
@@ -24,16 +24,30 @@ Hover on a day to see more details about it.
 
 - To change the date range, click the date dropdown in the chart's upper right corner and choose a new date range.
 
+## Workspace-level data worker usage
+
+On capacity-based plans with data worker entitlements, the workspace Usage page shows data worker usage instead of credit usage. Workspace editors can view data worker usage for their workspace.
+
+1. Click **Workspace Settings** > **Usage**.
+
+2. Review the line graph, which shows hourly data worker usage over a 7-day period for the current workspace.
+
+This helps you understand your workspace's contribution to overall organization capacity usage.
+
 ## What to do if you hit your data worker limit
 
-An infrequent instance of maximum usage probably isn't a problem. If you're regularly hitting your data worker limit, you have three options.
+An infrequent instance of maximum usage probably isn't a problem. If you're regularly hitting your data worker limit, you have four options.
 
-- Accept that Airbyte may queue or throttle your connections.
+- Accept that Airbyte may queue your connections. If a connection already has a queued sync and its next scheduled run arrives, the newer run replaces the older queued one so the most recent data syncs when capacity frees up.
 
 - Reschedule some connections so they run at different times of the day, week, or month.
 
 - Buy more data workers to increase capacity.
 
+- Enable [on-demand capacity](#on-demand-capacity) for critical connections so they always run, even when committed capacity is exhausted.
+
+Manually triggered syncs that remain queued for 8 hours are automatically cancelled.
+
 ### Optimize data worker usage
 
 If you can, it's preferable to optimize Airbyte by rescheduling connections outside of busy periods.
@@ -53,3 +67,27 @@ If you can, it's preferable to optimize Airbyte by rescheduling connections outs
 ### Buy more data workers
 
 If you've tried to optimize scheduling and still need more data workers, contact your Airbyte representative or [talk to sales](https://www.airbyte.com/talk-to-sales).
+
+## On-demand capacity
+
+For critical data pipelines that must always run on time, you can enable on-demand capacity on individual connections. When committed capacity is available, the sync uses it at no extra cost. When committed capacity is exhausted, the sync runs immediately instead of being queued.
+
+Once your organization administrator enables on-demand capacity at the organization level, organization admins and workspace admins can enable it per connection. Other roles can view the toggle but cannot change it.
+
+### Enable on-demand capacity on a connection
+
+1. Click **Connections** and select the connection you want to configure.
+
+2. Click **Settings**.
+
+3. Toggle **Use on-demand capacity**. The toggle description reads: "Enable on demand capacity for this connection. Syncs for this connection will never be queued. Syncs that run when committed data worker is exhausted will be charged a premium rate." You must have the organization admin or workspace admin role to change this toggle.
+
+You can also enable on-demand capacity when first creating a connection. The toggle appears in the connection configuration during setup.
+
+When you enable on-demand capacity on a connection, Airbyte automatically applies a "Burst" tag (![Burst](./assets/burst-tag.png)) with an orange gradient background and a star icon. You can filter connections by the Burst tag to see all on-demand connections at a glance. If you disable on-demand capacity, Airbyte removes the Burst tag automatically. For more information about tags, see [Tagging connections](/platform/using-airbyte/tagging).
+
+### Identify queued connections
+
+When your committed capacity is fully utilized, connections waiting for capacity display an orange hourglass icon and a "Queued" status. You can filter the Connections page by "Queued" status to find all queued connections. A dismissable yellow banner also appears at the top of the Connections page: "Maximum capacity currently reached, additional jobs will be queued until capacity is available."
+
+For more information about connection statuses, see [Connection status](./review-connection-status.md).

docs/platform/cloud/managing-airbyte-cloud/review-connection-status.md

@@ -42,15 +42,28 @@ To view the connection status:
 
 3. Select a single connection to view more details about the connection and for a breakdown of the status of each Stream in that connection.  
 
-    | Icon                                               | Status      | Description                                                         |
-    | -------------------------------------------------- | ----------- | ------------------------------------------------------------------- |
-    | ![Healthy](./assets/connection_synced.png)         | **Healthy** | The most recent sync for this connection succeeded                  |
-    | ![Failed](./assets/connection_action_required.png) | **Failed**  | The most recent sync for this connection failed                     |
-    | ![Running](./assets/connection_syncing.png)        | **Running** | The connection is currently actively syncing                        |
-    | ![Paused](./assets/connection_disabled.png)        | **Paused**  | The connection is disabled and isn't scheduled to run automatically |
+    | Icon                                               | Status      | Description                                                                                          |
+    | -------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
+    | ![Healthy](./assets/connection_synced.png)         | **Healthy** | The most recent sync for this connection succeeded                                                   |
+    | ![Failed](./assets/connection_action_required.png) | **Failed**  | The most recent sync for this connection failed                                                      |
+    | ![Running](./assets/connection_syncing.png)        | **Running** | The connection is currently actively syncing                                                         |
+    | ![Paused](./assets/connection_disabled.png)        | **Paused**  | The connection is disabled and isn't scheduled to run automatically                                  |
+    | ![Queued](./assets/connection_queued.png)          | **Queued**  | The connection's sync is waiting for data worker capacity to become available (Cloud Pro and Enterprise Flex only) |
 
 4. On the **Status** tab for a connection, there is a list of associated Streams. To the left of the name for each Stream, there is an icon that displays its status.
 
+### Queued connections (Cloud Pro and Enterprise Flex)
+
+On capacity-based Cloud plans, when your organization's committed data worker capacity is fully utilized, newly triggered sync jobs enter a "Queued" state. Queued connections display an orange hourglass icon.
+
+A queued job is cancelled when:
+
+- The connection is updated, cancelled, deleted, or reset.
+- The next scheduled sync for that connection arrives. The newer sync replaces the queued one so the most recent data syncs when capacity frees up.
+- Eight hours have elapsed for manually triggered syncs.
+
+You can filter the Connections page by "Queued" status to identify all queued connections. For information about monitoring and managing data worker capacity, see [Monitor data worker usage](./manage-data-workers.md).
+
 ## Review one stream's status
 
 The stream status allows you to monitor an individual stream's latest status. Connections often sync more than one stream. This view allows you to more easily determine if there is a problem with a given stream that could be causing problems with the connection.
@@ -64,6 +77,10 @@ The stream status allows you to monitor an individual stream's latest status. Co
 | ![Error](./assets/connection_incomplete.png)                    | **Error**                | The connection didn't succeed on its most recent sync, but Airbyte expects it to recover on the next one                                                 |
 | ![Action Required](./assets/connection_action_required.png)     | **Action Required**      | A breaking change related to the source or destination requires attention to resolve                                                               |
 
+:::note
+Stream-level "Queued" status means the stream is waiting to sync within an active connection sync. This is different from a connection-level "Queued" status, which means the entire sync job is waiting for data worker capacity. When a connection is queued for data worker capacity, its individual streams display as **Pending** (not Queued). For more information about capacity-based queuing, see [Monitor data worker usage](./manage-data-workers.md).
+:::
+
 Once the sync is complete, each stream displays the time since Airbyte loaded the last record to the destination. You can click **Last record loaded** in the header to optionally display the exact datetime the last record loaded.
 
 ## Per-stream actions

docs/platform/cloud/managing-airbyte-cloud/review-connection-timeline.md

@@ -63,6 +63,9 @@ Completed syncs, [refreshes](/platform/operator-guides/refreshes), and [clears](
 | Failed     | The sync encountered a fatal error, and needs intervention to resolve. Airbyte loaded a subset or none of the data to the destination. |
 | Cancelled  | Someone cancelled the sync before it finished.                                                                                          |
 | Running    | The sync is currently running.                                                                                                         |
+| Queued     | The sync is waiting for data worker capacity to become available. (Cloud Pro and Enterprise Flex only)                                  |
+
+Queued syncs may appear as "Cancelled" in the timeline if they were cancelled due to a connection update, the next scheduled run arriving, or the 8-hour timeout for manual syncs. For more information about capacity queuing, see [Monitor data worker usage](./manage-data-workers.md).
 
 ### How the Connection Timeline reflects moved data
 

docs/platform/cloud/managing-airbyte-cloud/understand-airbyte-cloud-limits.md

@@ -22,6 +22,12 @@ These limitations only apply to those using the Standard plan. If you upgrade to
 
 - Size of a single record: 20MB\*\*
 
+## Pro and Enterprise Flex plan considerations
+
+Organizations on capacity-based plans (Pro, Enterprise Flex) have a contracted number of data workers. When all data workers are in use, additional syncs are queued until capacity becomes available. This is not a hard limit on the number of connections or syncs you can create, but a limit on concurrent sync execution.
+
+You can enable on-demand capacity for critical connections so they run even when committed capacity is exhausted. See [Monitor data worker usage](./manage-data-workers.md) for details.
+
 \*\* The effective maximum size of the record may vary based per destination. Some destinations may
 fail to sync if a record cannot be stored, but Destinations which support
 [typing and deduping](/platform/using-airbyte/core-concepts/typing-deduping) will adjust your record so that

docs/platform/understanding-airbyte/jobs.md

@@ -84,6 +84,7 @@ direction TB
 state NonTerminal {
     [*] --> pending
     pending
+    queued
     running
     incomplete
     note left of incomplete
@@ -97,7 +98,9 @@ note left of NonSuccess
     All Non Terminal Statuses can be transitioned to cancelled or failed
 end note
 
-pending --> running
+pending --> queued : capacity enforcement active,\nno capacity available
+pending --> running : capacity available
+queued --> running : capacity becomes available
 running --> incomplete
 incomplete --> running
 running --> succeeded
@@ -118,6 +121,18 @@ stateDiagram-v2
     running --> failed
 ```
 
+### Queued state (Cloud Pro and Enterprise Flex)
+
+On capacity-based Cloud plans, the `queued` state is used when capacity enforcement is active and all committed data workers are in use. A job transitions from `pending` to `queued` when no capacity is available. The job stays in `queued` until capacity frees up, at which point it transitions to `running`.
+
+A queued job is cancelled if:
+
+- The connection is modified, cancelled, deleted, or reset.
+- The next scheduled sync for that connection arrives. The newer sync replaces the queued one.
+- Eight hours have elapsed for manually triggered syncs.
+
+Capacity enforcement applies only to sync jobs, not to check, discover, or spec operations. For more information, see [Monitor data worker usage](/platform/cloud/managing-airbyte-cloud/manage-data-workers).
+
 ### Attempts and Retries
 
 In the event of a failure, the Airbyte platform will retry the pipeline. Each of these sub-invocations of a job is called an attempt.

docs/platform/using-airbyte/core-concepts/sync-schedules.md

@@ -61,6 +61,8 @@ It can be triggered by clicking the "Sync Now" button at any time through the UI
 - Only one sync per connection can run at a time.
 - If a sync is scheduled to run before the previous sync finishes, the scheduled sync will start after the completion of the previous sync.
 - Syncs can run at most every 60 minutes in Airbyte Cloud. Reach out to [Sales](https://airbyte.com/company/talk-to-sales) if you require replication more frequently than once per hour.
+- On capacity-based Cloud plans, if all committed data workers are in use, newly triggered syncs are queued until capacity is available. You can enable [on-demand capacity](/platform/cloud/managing-airbyte-cloud/manage-data-workers#on-demand-capacity) for critical connections so they always run on time.
+- If a connection has a queued sync and its next scheduled run arrives, the newer scheduled run replaces the queued one. This ensures that when capacity frees up, the most recent data is synced rather than stale data from the original trigger.
 
 :::note
 For Scheduled or cron scheduled syncs, Airbyte guarantees syncs will initiate with a schedule accuracy of +/- 30 minutes.

docs/platform/using-airbyte/tagging.md

@@ -92,6 +92,23 @@ Delete a tag from Airbyte and remove it from any connections that use it.
 
 Airbyte deletes the tag and removes it from any connections that use it.
 
+## System tags
+
+In addition to user-created tags, Airbyte can automatically apply system-generated tags to connections.
+
+### Burst tag (Cloud Pro and Enterprise Flex)
+
+When you enable [on-demand capacity](/platform/cloud/managing-airbyte-cloud/manage-data-workers#on-demand-capacity) for a connection, Airbyte automatically applies a "Burst" tag. This tag has an orange gradient background with a star icon and is visually distinct from user-created tags.
+
+![Burst tag](images/burst-tag.png)
+
+- The Burst tag appears automatically when you enable "Use on-demand capacity" in a connection's Settings.
+- The Burst tag is removed automatically when you disable on-demand capacity.
+- You can filter the Connections page by the Burst tag to see all on-demand connections.
+- Hovering on the Burst tag displays a tooltip: "This connection uses on-demand capacity for syncs".
+
+You cannot manually create, edit, or delete system tags.
+
 ## Limitations
 
 Tags have the following maximums.