From 84536550afb19a4e42a97bf08f14bcea1bbf9928 Mon Sep 17 00:00:00 2001 From: CahidArda Date: Mon, 16 Feb 2026 14:08:29 +0300 Subject: [PATCH 1/3] docs: add flow control management API documentation Document new flow control list, get, and reset endpoints. Add SDK examples for TypeScript and Python. Update OpenAPI spec and changelog. DX-2401 Co-Authored-By: Claude Opus 4.6 --- docs.json | 9 +- qstash/features/flowcontrol.mdx | 134 ++++++++++++++++++++- qstash/openapi.yaml | 80 +++++++++++- qstash/overall/changelog.mdx | 11 ++ qstash/sdks/py/examples/flow-control.mdx | 44 +++++++ qstash/sdks/ts/examples/flow-control.mdx | 44 +++++++ workflow/features/flow-control/monitor.mdx | 44 ++++++- workflow/rest/flow-control/get.mdx | 41 ++++++- workflow/rest/flow-control/list.mdx | 52 +++++++- workflow/rest/flow-control/reset.mdx | 27 +++++ 10 files changed, 474 insertions(+), 12 deletions(-) create mode 100644 qstash/sdks/py/examples/flow-control.mdx create mode 100644 qstash/sdks/ts/examples/flow-control.mdx create mode 100644 workflow/rest/flow-control/reset.mdx diff --git a/docs.json b/docs.json index 5e06d314..65e9e7aa 100644 --- a/docs.json +++ b/docs.json @@ -1097,7 +1097,8 @@ "qstash/sdks/ts/examples/logs", "qstash/sdks/ts/examples/messages", "qstash/sdks/ts/examples/receiver", - "qstash/sdks/ts/examples/queues" + "qstash/sdks/ts/examples/queues", + "qstash/sdks/ts/examples/flow-control" ] } ] @@ -1119,7 +1120,8 @@ "qstash/sdks/py/examples/messages", "qstash/sdks/py/examples/keys", "qstash/sdks/py/examples/receiver", - "qstash/sdks/py/examples/queues" + "qstash/sdks/py/examples/queues", + "qstash/sdks/py/examples/flow-control" ] } ] @@ -1345,8 +1347,9 @@ { "group": "Flow Control", "pages": [ + "workflow/rest/flow-control/list", "workflow/rest/flow-control/get", - "workflow/rest/flow-control/list" + "workflow/rest/flow-control/reset" ] }, { diff --git a/qstash/features/flowcontrol.mdx b/qstash/features/flowcontrol.mdx index 3d252861..672ac610 100644 --- a/qstash/features/flowcontrol.mdx +++ b/qstash/features/flowcontrol.mdx @@ -101,7 +101,137 @@ curl -XPOST -H 'Authorization: Bearer XXX' \ ``` -## Monitor +## Management API + +You can inspect and reset flow control keys programmatically using the `flowControl` namespace on the client. + +### List all flow control keys + +Returns all active flow control keys along with their current metrics. + + +```typescript TypeScript +import { Client } from "@upstash/qstash"; + +const client = new Client({ token: "" }); + +const controls = await client.flowControl.list(); +// controls is an array of FlowControlInfo objects +console.log(controls); +``` + +```python Python +from qstash import QStash + +client = QStash("") + +controls = client.flow_control.list() +print(controls) +``` + +```bash cURL +curl -X GET https://qstash.upstash.io/v2/flowControl \ + -H "Authorization: Bearer " +``` + + +You can also filter keys by a search string: + +```bash cURL +curl -X GET "https://qstash.upstash.io/v2/flowControl?search=my-key" \ + -H "Authorization: Bearer " +``` + +### Get a single flow control key + +Returns the current state and metrics for one flow control key. + + +```typescript TypeScript +import { Client } from "@upstash/qstash"; + +const client = new Client({ token: "" }); + +const info = await client.flowControl.get("USER_GIVEN_KEY"); +console.log(info); +// { +// flowControlKey: "USER_GIVEN_KEY", +// waitListSize: 5, +// parallelismMax: 10, +// parallelismCount: 3, +// rateMax: 100, +// rateCount: 42, +// ratePeriod: 60, +// ratePeriodStart: 1708000000 +// } +``` + +```python Python +from qstash import QStash + +client = QStash("") + +info = client.flow_control.get("USER_GIVEN_KEY") +print(info) +# FlowControlInfo( +# key="USER_GIVEN_KEY", +# wait_list_size=5, +# parallelism_max=10, +# parallelism_count=3, +# rate_max=100, +# rate_count=42, +# rate_period=60, +# rate_period_start=1708000000 +# ) +``` + +```bash cURL +curl -X GET https://qstash.upstash.io/v2/flowControl/USER_GIVEN_KEY \ + -H "Authorization: Bearer " +``` + + +The response fields are: + +| Field | Description | +|---|---| +| `flowControlKey` | The flow control key name | +| `waitListSize` | Number of messages currently waiting in the queue | +| `parallelismMax` | Configured maximum concurrent messages (if set) | +| `parallelismCount` | Number of messages currently running in parallel | +| `rateMax` | Configured maximum messages per rate period (if set) | +| `rateCount` | Number of messages dispatched in the current rate period | +| `ratePeriod` | Rate period length in seconds | +| `ratePeriodStart` | Unix timestamp when the current rate period started | + +### Reset a flow control key + +Resets the counters for a flow control key. This is useful when you want to allow queued messages to be dispatched immediately, for example after recovering from a downstream outage. + + +```typescript TypeScript +import { Client } from "@upstash/qstash"; + +const client = new Client({ token: "" }); + +await client.flowControl.reset("USER_GIVEN_KEY"); +``` + +```python Python +from qstash import QStash + +client = QStash("") + +client.flow_control.reset("USER_GIVEN_KEY") +``` + +```bash cURL +curl -X POST https://qstash.upstash.io/v2/flowControl/USER_GIVEN_KEY/reset \ + -H "Authorization: Bearer " +``` + + +## Monitor You can monitor wait list size of your flow control key's from the console `FlowControl` tab. @@ -109,6 +239,6 @@ You can monitor wait list size of your flow control key's from the console `Flow -Also you can get the same info using the REST API. +Also you can get the same info using the REST API. - [List All Flow Control Keys](/qstash/api/flow-control/list). - [Single Flow Control Key](/qstash/api/flow-control/get). diff --git a/qstash/openapi.yaml b/qstash/openapi.yaml index 91543d7e..371c7cff 100644 --- a/qstash/openapi.yaml +++ b/qstash/openapi.yaml @@ -291,9 +291,27 @@ components: flowControlKey: type: string description: The flow control key name - waitlistSize: + waitListSize: type: integer description: The number of messages waiting due to flow control configuration. + parallelismMax: + type: integer + description: The configured maximum number of messages allowed to run concurrently, if parallelism is set. + parallelismCount: + type: integer + description: The current number of messages running in parallel. + rateMax: + type: integer + description: The configured maximum number of messages allowed per rate period, if rate limiting is set. + rateCount: + type: integer + description: The number of messages dispatched in the current rate period. + ratePeriod: + type: integer + description: The length of the rate period in seconds. + ratePeriodStart: + type: integer + description: Unix timestamp (seconds) when the current rate period started. DLQMessage: type: object @@ -2392,14 +2410,23 @@ paths: description: List all Flow Control keys tags: - Flow Control + parameters: + - name: search + in: query + required: false + schema: + type: string + description: Optional search string to filter flow control keys by name responses: '200': description: Flow control keys retrieved successfully content: application/json: schema: - $ref: '#/components/schemas/FlowControlKey' - + type: array + items: + $ref: '#/components/schemas/FlowControlKey' + /v2/flowControl/{flowControlKey}: get: summary: Get Flow Control Key @@ -2426,6 +2453,53 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + + /v2/flowControl/{flowControlKey}/reset: + post: + summary: Reset Flow Control Key + description: > + Resets the parallelism and rate counters for the specified flow control key. + Use this to allow queued messages to be dispatched immediately, for example + after recovering from a downstream outage. + tags: + - Flow Control + parameters: + - name: flowControlKey + in: path + required: true + schema: + type: string + description: The Flow Control key to reset + responses: + '200': + description: Flow control key reset successfully + '404': + description: Flow Control key not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /v2/globalParallelism: + get: + summary: Get Global Parallelism + description: Returns the current global parallelism usage across all flow control keys + tags: + - Flow Control + responses: + '200': + description: Global parallelism info retrieved successfully + content: + application/json: + schema: + type: object + properties: + parallelismMax: + type: integer + description: The configured maximum global parallelism + parallelismCount: + type: integer + description: The current number of messages running globally in parallel /v2/keys: get: diff --git a/qstash/overall/changelog.mdx b/qstash/overall/changelog.mdx index a46031cb..c0c56fd2 100644 --- a/qstash/overall/changelog.mdx +++ b/qstash/overall/changelog.mdx @@ -6,6 +6,17 @@ title: Changelog We have moved the roadmap and the changelog to [Github Discussions](https://github.com/orgs/upstash/discussions) starting from October 2025.Now you can follow `In Progress` features. You can see that your `Feature Requests` are recorded. You can vote for them and comment your specific use-cases to shape the feature to your needs. + +- **TypeScript SDK (`qstash-js`)** and **Python SDK (`qstash-py`):** + - Added flow control management API: `list()`, `get(key)`, and `reset(key)` methods on `client.flowControl` (TypeScript) and `client.flow_control` (Python). + - The `get` and `list` responses now include rich metrics: `waitListSize`, `parallelismMax`, `parallelismCount`, `rateMax`, `rateCount`, `ratePeriod`, and `ratePeriodStart`. + - See the [Flow Control](/qstash/features/flowcontrol#management-api) docs for code examples. +- **QStash Server:** + - `GET /v2/flowControl` now supports an optional `search` query parameter to filter keys by name. + - New `POST /v2/flowControl/:flowControlKey/reset` endpoint resets parallelism and rate counters for a key. + - `GET /v2/globalParallelism` now returns `{ parallelismMax, parallelismCount }` instead of the old `{ waitListSize }` shape. + + - **TypeScript SDK (`qstash-js`):** - `Label` feature is added. This will enable our users to label their publishes so that diff --git a/qstash/sdks/py/examples/flow-control.mdx b/qstash/sdks/py/examples/flow-control.mdx new file mode 100644 index 00000000..e6cebf4c --- /dev/null +++ b/qstash/sdks/py/examples/flow-control.mdx @@ -0,0 +1,44 @@ +--- +title: Flow Control +--- + +#### List all flow control keys + +```python +from qstash import QStash + +client = QStash("") + +controls = client.flow_control.list() +print(controls) +``` + +#### Get a single flow control key + +```python +from qstash import QStash + +client = QStash("") + +info = client.flow_control.get("USER_GIVEN_KEY") +print(info.key) +print(info.wait_list_size) +print(info.parallelism_max) +print(info.parallelism_count) +print(info.rate_max) +print(info.rate_count) +print(info.rate_period) +print(info.rate_period_start) +``` + +#### Reset a flow control key + +Resetting clears the parallelism and rate counters, allowing queued messages to be dispatched immediately. + +```python +from qstash import QStash + +client = QStash("") + +client.flow_control.reset("USER_GIVEN_KEY") +``` diff --git a/qstash/sdks/ts/examples/flow-control.mdx b/qstash/sdks/ts/examples/flow-control.mdx new file mode 100644 index 00000000..58ba3ff2 --- /dev/null +++ b/qstash/sdks/ts/examples/flow-control.mdx @@ -0,0 +1,44 @@ +--- +title: Flow Control +--- + +#### List all flow control keys + +```typescript +import { Client } from "@upstash/qstash"; + +const client = new Client({ token: "" }); + +const controls = await client.flowControl.list(); +console.log(controls); +``` + +#### Get a single flow control key + +```typescript +import { Client } from "@upstash/qstash"; + +const client = new Client({ token: "" }); + +const info = await client.flowControl.get("USER_GIVEN_KEY"); +console.log(info.flowControlKey); +console.log(info.waitListSize); +console.log(info.parallelismMax); +console.log(info.parallelismCount); +console.log(info.rateMax); +console.log(info.rateCount); +console.log(info.ratePeriod); +console.log(info.ratePeriodStart); +``` + +#### Reset a flow control key + +Resetting clears the parallelism and rate counters, allowing queued messages to be dispatched immediately. + +```typescript +import { Client } from "@upstash/qstash"; + +const client = new Client({ token: "" }); + +await client.flowControl.reset("USER_GIVEN_KEY"); +``` diff --git a/workflow/features/flow-control/monitor.mdx b/workflow/features/flow-control/monitor.mdx index 1820de21..6581b273 100644 --- a/workflow/features/flow-control/monitor.mdx +++ b/workflow/features/flow-control/monitor.mdx @@ -8,7 +8,49 @@ You can monitor wait list size of your flow control key's from the console `Flow -Also you can get the same info using the REST API. +Also you can get the same info using the REST API. - [List All Flow Control Keys](/workflow/rest/flow-control/list). - [Single Flow Control Key](/workflow/rest/flow-control/get). +- [Reset Flow Control Key](/workflow/rest/flow-control/reset). +## Response Fields + +Each flow control key returned by the API includes the following metrics: + +| Field | Description | +|---|---| +| `flowControlKey` | The flow control key name | +| `waitListSize` | Number of messages currently waiting in the queue | +| `parallelismMax` | Configured maximum concurrent messages (if set) | +| `parallelismCount` | Number of messages currently running in parallel | +| `rateMax` | Configured maximum messages per rate period (if set) | +| `rateCount` | Number of messages dispatched in the current rate period | +| `ratePeriod` | Rate period length in seconds | +| `ratePeriodStart` | Unix timestamp when the current rate period started | + +## Resetting a Flow Control Key + +If you need to immediately release queued messages (for example, after a downstream service recovers from an outage), you can reset the flow control counters via the REST API or SDK: + + +```typescript TypeScript +import { Client } from "@upstash/workflow"; + +const client = new Client({ token: "" }); + +await client.flowControl.reset("your-flow-control-key"); +``` + +```python Python +from qstash import QStash + +client = QStash("") + +client.flow_control.reset("your-flow-control-key") +``` + +```bash cURL +curl -X POST https://qstash.upstash.io/v2/flowControl/your-flow-control-key/reset \ + -H "Authorization: Bearer " +``` + diff --git a/workflow/rest/flow-control/get.mdx b/workflow/rest/flow-control/get.mdx index a9257bc9..6afa279a 100644 --- a/workflow/rest/flow-control/get.mdx +++ b/workflow/rest/flow-control/get.mdx @@ -14,15 +14,54 @@ authMethod: "bearer" ## Response - The key of of the flow control. + The key of the flow control. The number of messages in the wait list that waits for `parallelism`/`rate` set in the flow control. + + The configured maximum number of messages allowed to run concurrently, if parallelism is set. + + + + The current number of messages running in parallel. + + + + The configured maximum number of messages allowed per rate period, if rate limiting is set. + + + + The number of messages dispatched in the current rate period. + + + + The length of the rate period in seconds. + + + + Unix timestamp (seconds) when the current rate period started. + + ```sh curl -X GET https://qstash.upstash.io/v2/flowControl/YOUR_FLOW_CONTROL_KEY -H "Authorization: Bearer " ``` + + +```json +{ + "flowControlKey": "YOUR_FLOW_CONTROL_KEY", + "waitListSize": 5, + "parallelismMax": 10, + "parallelismCount": 3, + "rateMax": 100, + "rateCount": 42, + "ratePeriod": 60, + "ratePeriodStart": 1708000000 +} +``` + diff --git a/workflow/rest/flow-control/list.mdx b/workflow/rest/flow-control/list.mdx index ec8d6c36..65436a89 100644 --- a/workflow/rest/flow-control/list.mdx +++ b/workflow/rest/flow-control/list.mdx @@ -1,11 +1,18 @@ --- title: "List Flow-Control Keys" description: "List All Flow Control Keys" -api: "GET https://qstash.upstash.io/v2/flowControl/" +api: "GET https://qstash.upstash.io/v2/flowControl" authMethod: "bearer" --- +## Request + + + Optional search string to filter flow control keys by name. + + ## Response + @@ -15,11 +22,52 @@ authMethod: "bearer" The number of messages in the wait list that waits for `parallelism`/`rate` set in the flow control. + + + The configured maximum number of messages allowed to run concurrently, if parallelism is set. + + + + The current number of messages running in parallel. + + + + The configured maximum number of messages allowed per rate period, if rate limiting is set. + + + + The number of messages dispatched in the current rate period. + + + + The length of the rate period in seconds. + + + + Unix timestamp (seconds) when the current rate period started. + ```sh -curl -X GET https://qstash.upstash.io/v2/flowControl/ -H "Authorization: Bearer " +curl -X GET https://qstash.upstash.io/v2/flowControl -H "Authorization: Bearer " ``` + + +```json +[ + { + "flowControlKey": "my-key", + "waitListSize": 5, + "parallelismMax": 10, + "parallelismCount": 3, + "rateMax": 100, + "rateCount": 42, + "ratePeriod": 60, + "ratePeriodStart": 1708000000 + } +] +``` + diff --git a/workflow/rest/flow-control/reset.mdx b/workflow/rest/flow-control/reset.mdx new file mode 100644 index 00000000..0ed9acc5 --- /dev/null +++ b/workflow/rest/flow-control/reset.mdx @@ -0,0 +1,27 @@ +--- +title: "Reset Flow-Control" +description: "Reset counters for a Flow-Control key" +api: "POST https://qstash.upstash.io/v2/flowControl/{flowControlKey}/reset" +authMethod: "bearer" +--- + +Resets the parallelism and rate counters for the specified flow control key. +This is useful when you want to allow queued messages to be dispatched immediately, +for example after recovering from a downstream outage. + +## Request + + + The key of the flow control to reset. See the [flow control](/workflow/features/flow-control) for more details. + + +## Response + +Returns an empty `200 OK` response on success. + + +```sh +curl -X POST https://qstash.upstash.io/v2/flowControl/YOUR_FLOW_CONTROL_KEY/reset \ + -H "Authorization: Bearer " +``` + From 3f89bae99afab03b45461ea7f2367c7591300d2c Mon Sep 17 00:00:00 2001 From: CahidArda Date: Wed, 18 Feb 2026 12:53:49 +0300 Subject: [PATCH 2/3] DX-2401: Update flow control docs - add global parallelism, remove list/reset - Add getGlobalParallelism to SDK examples and feature docs - Add global-parallelism REST API page - Remove list and reset REST API pages - Update monitoring page and navigation Co-Authored-By: Claude Opus 4.6 --- docs.json | 3 +- qstash/features/flowcontrol.mdx | 66 ++++++----------- qstash/sdks/py/examples/flow-control.mdx | 19 +---- qstash/sdks/ts/examples/flow-control.mdx | 19 +---- workflow/features/flow-control/monitor.mdx | 30 +------- .../rest/flow-control/global-parallelism.mdx | 31 ++++++++ workflow/rest/flow-control/list.mdx | 73 ------------------- workflow/rest/flow-control/reset.mdx | 27 ------- 8 files changed, 63 insertions(+), 205 deletions(-) create mode 100644 workflow/rest/flow-control/global-parallelism.mdx delete mode 100644 workflow/rest/flow-control/list.mdx delete mode 100644 workflow/rest/flow-control/reset.mdx diff --git a/docs.json b/docs.json index 65e9e7aa..56a0538c 100644 --- a/docs.json +++ b/docs.json @@ -1347,9 +1347,8 @@ { "group": "Flow Control", "pages": [ - "workflow/rest/flow-control/list", "workflow/rest/flow-control/get", - "workflow/rest/flow-control/reset" + "workflow/rest/flow-control/global-parallelism" ] }, { diff --git a/qstash/features/flowcontrol.mdx b/qstash/features/flowcontrol.mdx index 672ac610..591cab95 100644 --- a/qstash/features/flowcontrol.mdx +++ b/qstash/features/flowcontrol.mdx @@ -103,44 +103,7 @@ curl -XPOST -H 'Authorization: Bearer XXX' \ ## Management API -You can inspect and reset flow control keys programmatically using the `flowControl` namespace on the client. - -### List all flow control keys - -Returns all active flow control keys along with their current metrics. - - -```typescript TypeScript -import { Client } from "@upstash/qstash"; - -const client = new Client({ token: "" }); - -const controls = await client.flowControl.list(); -// controls is an array of FlowControlInfo objects -console.log(controls); -``` - -```python Python -from qstash import QStash - -client = QStash("") - -controls = client.flow_control.list() -print(controls) -``` - -```bash cURL -curl -X GET https://qstash.upstash.io/v2/flowControl \ - -H "Authorization: Bearer " -``` - - -You can also filter keys by a search string: - -```bash cURL -curl -X GET "https://qstash.upstash.io/v2/flowControl?search=my-key" \ - -H "Authorization: Bearer " -``` +You can inspect flow control keys programmatically using the `flowControl` namespace on the client. ### Get a single flow control key @@ -204,9 +167,9 @@ The response fields are: | `ratePeriod` | Rate period length in seconds | | `ratePeriodStart` | Unix timestamp when the current rate period started | -### Reset a flow control key +### Get global parallelism -Resets the counters for a flow control key. This is useful when you want to allow queued messages to be dispatched immediately, for example after recovering from a downstream outage. +Returns the global parallelism usage across all flow control keys. ```typescript TypeScript @@ -214,7 +177,12 @@ import { Client } from "@upstash/qstash"; const client = new Client({ token: "" }); -await client.flowControl.reset("USER_GIVEN_KEY"); +const info = await client.flowControl.getGlobalParallelism(); +console.log(info); +// { +// parallelismMax: 500, +// parallelismCount: 42 +// } ``` ```python Python @@ -222,15 +190,25 @@ from qstash import QStash client = QStash("") -client.flow_control.reset("USER_GIVEN_KEY") +info = client.flow_control.get_global_parallelism() +print(info) +# GlobalParallelismInfo( +# parallelism_max=500, +# parallelism_count=42 +# ) ``` ```bash cURL -curl -X POST https://qstash.upstash.io/v2/flowControl/USER_GIVEN_KEY/reset \ +curl -X GET https://qstash.upstash.io/v2/globalParallelism \ -H "Authorization: Bearer " ``` +| Field | Description | +|---|---| +| `parallelismMax` | The maximum global parallelism | +| `parallelismCount` | The current number of active requests globally | + ## Monitor You can monitor wait list size of your flow control key's from the console `FlowControl` tab. @@ -240,5 +218,5 @@ You can monitor wait list size of your flow control key's from the console `Flow Also you can get the same info using the REST API. -- [List All Flow Control Keys](/qstash/api/flow-control/list). - [Single Flow Control Key](/qstash/api/flow-control/get). +- [Global Parallelism](/qstash/api/flow-control/global-parallelism). diff --git a/qstash/sdks/py/examples/flow-control.mdx b/qstash/sdks/py/examples/flow-control.mdx index e6cebf4c..aba5d9c4 100644 --- a/qstash/sdks/py/examples/flow-control.mdx +++ b/qstash/sdks/py/examples/flow-control.mdx @@ -2,17 +2,6 @@ title: Flow Control --- -#### List all flow control keys - -```python -from qstash import QStash - -client = QStash("") - -controls = client.flow_control.list() -print(controls) -``` - #### Get a single flow control key ```python @@ -31,14 +20,14 @@ print(info.rate_period) print(info.rate_period_start) ``` -#### Reset a flow control key - -Resetting clears the parallelism and rate counters, allowing queued messages to be dispatched immediately. +#### Get global parallelism ```python from qstash import QStash client = QStash("") -client.flow_control.reset("USER_GIVEN_KEY") +info = client.flow_control.get_global_parallelism() +print(info.parallelism_max) +print(info.parallelism_count) ``` diff --git a/qstash/sdks/ts/examples/flow-control.mdx b/qstash/sdks/ts/examples/flow-control.mdx index 58ba3ff2..5a957c79 100644 --- a/qstash/sdks/ts/examples/flow-control.mdx +++ b/qstash/sdks/ts/examples/flow-control.mdx @@ -2,17 +2,6 @@ title: Flow Control --- -#### List all flow control keys - -```typescript -import { Client } from "@upstash/qstash"; - -const client = new Client({ token: "" }); - -const controls = await client.flowControl.list(); -console.log(controls); -``` - #### Get a single flow control key ```typescript @@ -31,14 +20,14 @@ console.log(info.ratePeriod); console.log(info.ratePeriodStart); ``` -#### Reset a flow control key - -Resetting clears the parallelism and rate counters, allowing queued messages to be dispatched immediately. +#### Get global parallelism ```typescript import { Client } from "@upstash/qstash"; const client = new Client({ token: "" }); -await client.flowControl.reset("USER_GIVEN_KEY"); +const info = await client.flowControl.getGlobalParallelism(); +console.log(info.parallelismMax); +console.log(info.parallelismCount); ``` diff --git a/workflow/features/flow-control/monitor.mdx b/workflow/features/flow-control/monitor.mdx index 6581b273..ec3151bb 100644 --- a/workflow/features/flow-control/monitor.mdx +++ b/workflow/features/flow-control/monitor.mdx @@ -9,9 +9,8 @@ You can monitor wait list size of your flow control key's from the console `Flow Also you can get the same info using the REST API. -- [List All Flow Control Keys](/workflow/rest/flow-control/list). - [Single Flow Control Key](/workflow/rest/flow-control/get). -- [Reset Flow Control Key](/workflow/rest/flow-control/reset). +- [Global Parallelism](/workflow/rest/flow-control/global-parallelism). ## Response Fields @@ -27,30 +26,3 @@ Each flow control key returned by the API includes the following metrics: | `rateCount` | Number of messages dispatched in the current rate period | | `ratePeriod` | Rate period length in seconds | | `ratePeriodStart` | Unix timestamp when the current rate period started | - -## Resetting a Flow Control Key - -If you need to immediately release queued messages (for example, after a downstream service recovers from an outage), you can reset the flow control counters via the REST API or SDK: - - -```typescript TypeScript -import { Client } from "@upstash/workflow"; - -const client = new Client({ token: "" }); - -await client.flowControl.reset("your-flow-control-key"); -``` - -```python Python -from qstash import QStash - -client = QStash("") - -client.flow_control.reset("your-flow-control-key") -``` - -```bash cURL -curl -X POST https://qstash.upstash.io/v2/flowControl/your-flow-control-key/reset \ - -H "Authorization: Bearer " -``` - diff --git a/workflow/rest/flow-control/global-parallelism.mdx b/workflow/rest/flow-control/global-parallelism.mdx new file mode 100644 index 00000000..6ae2e0f5 --- /dev/null +++ b/workflow/rest/flow-control/global-parallelism.mdx @@ -0,0 +1,31 @@ +--- +title: "Get Global Parallelism" +description: "Get global parallelism usage" +api: "GET https://qstash.upstash.io/v2/globalParallelism" +authMethod: "bearer" +--- + +## Response + + + The configured maximum global parallelism. + + + + The current number of messages running globally in parallel. + + + +```sh +curl -X GET https://qstash.upstash.io/v2/globalParallelism -H "Authorization: Bearer " +``` + + + +```json +{ + "parallelismMax": 500, + "parallelismCount": 42 +} +``` + diff --git a/workflow/rest/flow-control/list.mdx b/workflow/rest/flow-control/list.mdx deleted file mode 100644 index 65436a89..00000000 --- a/workflow/rest/flow-control/list.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "List Flow-Control Keys" -description: "List All Flow Control Keys" -api: "GET https://qstash.upstash.io/v2/flowControl" -authMethod: "bearer" ---- - -## Request - - - Optional search string to filter flow control keys by name. - - -## Response - - - - - The key of the flow control. See the [flow control](/workflow/features/flow-control) for more details. - - - - The number of messages in the wait list that waits for `parallelism`/`rate` set in the flow control. - - - - The configured maximum number of messages allowed to run concurrently, if parallelism is set. - - - - The current number of messages running in parallel. - - - - The configured maximum number of messages allowed per rate period, if rate limiting is set. - - - - The number of messages dispatched in the current rate period. - - - - The length of the rate period in seconds. - - - - Unix timestamp (seconds) when the current rate period started. - - - - - -```sh -curl -X GET https://qstash.upstash.io/v2/flowControl -H "Authorization: Bearer " -``` - - - -```json -[ - { - "flowControlKey": "my-key", - "waitListSize": 5, - "parallelismMax": 10, - "parallelismCount": 3, - "rateMax": 100, - "rateCount": 42, - "ratePeriod": 60, - "ratePeriodStart": 1708000000 - } -] -``` - diff --git a/workflow/rest/flow-control/reset.mdx b/workflow/rest/flow-control/reset.mdx deleted file mode 100644 index 0ed9acc5..00000000 --- a/workflow/rest/flow-control/reset.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Reset Flow-Control" -description: "Reset counters for a Flow-Control key" -api: "POST https://qstash.upstash.io/v2/flowControl/{flowControlKey}/reset" -authMethod: "bearer" ---- - -Resets the parallelism and rate counters for the specified flow control key. -This is useful when you want to allow queued messages to be dispatched immediately, -for example after recovering from a downstream outage. - -## Request - - - The key of the flow control to reset. See the [flow control](/workflow/features/flow-control) for more details. - - -## Response - -Returns an empty `200 OK` response on success. - - -```sh -curl -X POST https://qstash.upstash.io/v2/flowControl/YOUR_FLOW_CONTROL_KEY/reset \ - -H "Authorization: Bearer " -``` - From 1a92db21e6ff88b6ffd21fc5e2c3fbc42e0cfbe5 Mon Sep 17 00:00:00 2001 From: CahidArda Date: Wed, 18 Feb 2026 13:01:55 +0300 Subject: [PATCH 3/3] fix: docs --- docs.json | 1 + qstash/features/flowcontrol.mdx | 1 + qstash/openapi.yaml | 33 ---------------------- workflow/features/flow-control/monitor.mdx | 16 +---------- workflow/rest/flow-control/list.mdx | 25 ++++++++++++++++ 5 files changed, 28 insertions(+), 48 deletions(-) create mode 100644 workflow/rest/flow-control/list.mdx diff --git a/docs.json b/docs.json index 56a0538c..1be02c92 100644 --- a/docs.json +++ b/docs.json @@ -1348,6 +1348,7 @@ "group": "Flow Control", "pages": [ "workflow/rest/flow-control/get", + "workflow/rest/flow-control/list", "workflow/rest/flow-control/global-parallelism" ] }, diff --git a/qstash/features/flowcontrol.mdx b/qstash/features/flowcontrol.mdx index 591cab95..a0f0ecbc 100644 --- a/qstash/features/flowcontrol.mdx +++ b/qstash/features/flowcontrol.mdx @@ -218,5 +218,6 @@ You can monitor wait list size of your flow control key's from the console `Flow Also you can get the same info using the REST API. +- [List All Flow Control Keys](/qstash/api/flow-control/list). - [Single Flow Control Key](/qstash/api/flow-control/get). - [Global Parallelism](/qstash/api/flow-control/global-parallelism). diff --git a/qstash/openapi.yaml b/qstash/openapi.yaml index 371c7cff..50a3db35 100644 --- a/qstash/openapi.yaml +++ b/qstash/openapi.yaml @@ -2410,13 +2410,6 @@ paths: description: List all Flow Control keys tags: - Flow Control - parameters: - - name: search - in: query - required: false - schema: - type: string - description: Optional search string to filter flow control keys by name responses: '200': description: Flow control keys retrieved successfully @@ -2454,32 +2447,6 @@ paths: schema: $ref: '#/components/schemas/Error' - /v2/flowControl/{flowControlKey}/reset: - post: - summary: Reset Flow Control Key - description: > - Resets the parallelism and rate counters for the specified flow control key. - Use this to allow queued messages to be dispatched immediately, for example - after recovering from a downstream outage. - tags: - - Flow Control - parameters: - - name: flowControlKey - in: path - required: true - schema: - type: string - description: The Flow Control key to reset - responses: - '200': - description: Flow control key reset successfully - '404': - description: Flow Control key not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - /v2/globalParallelism: get: summary: Get Global Parallelism diff --git a/workflow/features/flow-control/monitor.mdx b/workflow/features/flow-control/monitor.mdx index ec3151bb..38145a44 100644 --- a/workflow/features/flow-control/monitor.mdx +++ b/workflow/features/flow-control/monitor.mdx @@ -9,20 +9,6 @@ You can monitor wait list size of your flow control key's from the console `Flow Also you can get the same info using the REST API. +- [List All Flow Control Keys](/workflow/rest/flow-control/list). - [Single Flow Control Key](/workflow/rest/flow-control/get). - [Global Parallelism](/workflow/rest/flow-control/global-parallelism). - -## Response Fields - -Each flow control key returned by the API includes the following metrics: - -| Field | Description | -|---|---| -| `flowControlKey` | The flow control key name | -| `waitListSize` | Number of messages currently waiting in the queue | -| `parallelismMax` | Configured maximum concurrent messages (if set) | -| `parallelismCount` | Number of messages currently running in parallel | -| `rateMax` | Configured maximum messages per rate period (if set) | -| `rateCount` | Number of messages dispatched in the current rate period | -| `ratePeriod` | Rate period length in seconds | -| `ratePeriodStart` | Unix timestamp when the current rate period started | diff --git a/workflow/rest/flow-control/list.mdx b/workflow/rest/flow-control/list.mdx new file mode 100644 index 00000000..ec8d6c36 --- /dev/null +++ b/workflow/rest/flow-control/list.mdx @@ -0,0 +1,25 @@ +--- +title: "List Flow-Control Keys" +description: "List All Flow Control Keys" +api: "GET https://qstash.upstash.io/v2/flowControl/" +authMethod: "bearer" +--- + +## Response + + + + The key of the flow control. See the [flow control](/workflow/features/flow-control) for more details. + + + + The number of messages in the wait list that waits for `parallelism`/`rate` set in the flow control. + + + + + +```sh +curl -X GET https://qstash.upstash.io/v2/flowControl/ -H "Authorization: Bearer " +``` +