From 2b39e8c7495bb85de9004c50b9fb76193858d19e Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 11:35:06 +0000 Subject: [PATCH 1/8] Added Workflow instances batch creation instructions --- .../docs/workflows/build/workers-api.mdx | 22 +++++++++++++++++++ .../workflows/get-started/cli-quick-start.mdx | 1 + 2 files changed, 23 insertions(+) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index ca3e3e80c07a5e..cfa4ff7acbe89b 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -266,6 +266,28 @@ export default { } ``` +### createBatch + +Create (trigger) a batch of new instance of the given Workflow, up to 100 instances at a time. + +* createBatch(batch: WorkflowInstanceCreateOptions[]): Promise<WorkflowInstance[]> + + * `batch` - list of Options to pass when creating an instance, including a user-provided ID and payload parameters. + +Each element of the `batch` list is expected to the + +```ts +// Create a new batch of 3 Workflow instances, each with its own ID and pass params to the Workflow instances +const listOfInstances = [ + { id: "idFromBatch0", params: { "hello": "world-0" } }, + { id: "idFromBatch1", params: { "hello": "world-1" } }, + { id: "idFromBatch2", params: { "hello": "world-2" } } +]; +let instances = await env.MY_WORKFLOW.createBatch(listOfInstances); +``` + +Returns a list of `WorkflowInstance`. + ### get Get a specific Workflow instance by ID. diff --git a/src/content/docs/workflows/get-started/cli-quick-start.mdx b/src/content/docs/workflows/get-started/cli-quick-start.mdx index c70036a224680a..d8573317efc6e6 100644 --- a/src/content/docs/workflows/get-started/cli-quick-start.mdx +++ b/src/content/docs/workflows/get-started/cli-quick-start.mdx @@ -188,6 +188,7 @@ class_name = "MyWorkflow" You can then invoke the methods on this binding directly from your Worker script's `env` parameter. The `Workflow` type has methods for: * `create()` - creating (triggering) a new instance of the Workflow, returning the ID. +* `createBatch()` - creating (triggering) a batch of new instances of the Workflow, returning the IDs. * `get()`- retrieve a Workflow instance by its ID. * `status()` - get the current status of a unique Workflow instance. From 1f5f07e6a09a72393aace48c1875e553f1c4ad4e Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 12:46:44 +0000 Subject: [PATCH 2/8] Update src/content/docs/workflows/build/workers-api.mdx Co-authored-by: Matt Silverlock --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index cfa4ff7acbe89b..4f7a059403d665 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -286,7 +286,7 @@ const listOfInstances = [ let instances = await env.MY_WORKFLOW.createBatch(listOfInstances); ``` -Returns a list of `WorkflowInstance`. +Returns an array of `WorkflowInstance`. ### get From d9d2eb0a0f00d0977a9bc04c08bd5a81fd34cd4b Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 12:46:55 +0000 Subject: [PATCH 3/8] Update src/content/docs/workflows/build/workers-api.mdx Co-authored-by: Matt Silverlock --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index 4f7a059403d665..565d796df4753c 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -279,7 +279,7 @@ Each element of the `batch` list is expected to the ```ts // Create a new batch of 3 Workflow instances, each with its own ID and pass params to the Workflow instances const listOfInstances = [ - { id: "idFromBatch0", params: { "hello": "world-0" } }, + { id: "id-abc123", params: { "hello": "world-0" } }, { id: "idFromBatch1", params: { "hello": "world-1" } }, { id: "idFromBatch2", params: { "hello": "world-2" } } ]; From b9a2a2ebd400f2f94596c9d7725b417815b62e7a Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 12:47:02 +0000 Subject: [PATCH 4/8] Update src/content/docs/workflows/build/workers-api.mdx Co-authored-by: Matt Silverlock --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index 565d796df4753c..ac90e27546cfd0 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -280,7 +280,7 @@ Each element of the `batch` list is expected to the // Create a new batch of 3 Workflow instances, each with its own ID and pass params to the Workflow instances const listOfInstances = [ { id: "id-abc123", params: { "hello": "world-0" } }, - { id: "idFromBatch1", params: { "hello": "world-1" } }, + { id: "id-def456", params: { "hello": "world-1" } }, { id: "idFromBatch2", params: { "hello": "world-2" } } ]; let instances = await env.MY_WORKFLOW.createBatch(listOfInstances); From 733a897b068f6a125dd24807adafd66eb1ad4d63 Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 12:47:11 +0000 Subject: [PATCH 5/8] Update src/content/docs/workflows/build/workers-api.mdx Co-authored-by: Matt Silverlock --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index ac90e27546cfd0..e433d5311bfb79 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -281,7 +281,7 @@ Each element of the `batch` list is expected to the const listOfInstances = [ { id: "id-abc123", params: { "hello": "world-0" } }, { id: "id-def456", params: { "hello": "world-1" } }, - { id: "idFromBatch2", params: { "hello": "world-2" } } + { id: "id-ghi789", params: { "hello": "world-2" } } ]; let instances = await env.MY_WORKFLOW.createBatch(listOfInstances); ``` From b8fe8e8f5518eb88344e9aaacbb48cea5f5d5065 Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 12:47:34 +0000 Subject: [PATCH 6/8] Update src/content/docs/workflows/build/workers-api.mdx Co-authored-by: Matt Silverlock --- src/content/docs/workflows/build/workers-api.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index e433d5311bfb79..63b2d8aee59a78 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -270,6 +270,8 @@ export default { Create (trigger) a batch of new instance of the given Workflow, up to 100 instances at a time. +This is useful when you are scheduling multiple instances at once. A call to `createBatch` is treated the same as a call to `create` (for a single instance) and allows you to work within the [instance creation limit](/workflows/platform/limits/). + * createBatch(batch: WorkflowInstanceCreateOptions[]): Promise<WorkflowInstance[]> * `batch` - list of Options to pass when creating an instance, including a user-provided ID and payload parameters. From 77d5ebc1d9e4cffd2ce5b9a71b8fa89dbc120753 Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 15:03:37 +0000 Subject: [PATCH 7/8] Update src/content/docs/workflows/build/workers-api.mdx Co-authored-by: Matt Silverlock --- src/content/docs/workflows/build/workers-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index 63b2d8aee59a78..37b9f83ef9e141 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -270,7 +270,7 @@ export default { Create (trigger) a batch of new instance of the given Workflow, up to 100 instances at a time. -This is useful when you are scheduling multiple instances at once. A call to `createBatch` is treated the same as a call to `create` (for a single instance) and allows you to work within the [instance creation limit](/workflows/platform/limits/). +This is useful when you are scheduling multiple instances at once. A call to `createBatch` is treated the same as a call to `create` (for a single instance) and allows you to work within the [instance creation limit](/workflows/reference/limits/). * createBatch(batch: WorkflowInstanceCreateOptions[]): Promise<WorkflowInstance[]> From 95f3b0506e43f8b7ba310917bfd0d940b1614b23 Mon Sep 17 00:00:00 2001 From: Diogo Ferreira Date: Thu, 13 Mar 2025 15:06:34 +0000 Subject: [PATCH 8/8] updated rules of workflows with batch creation instructions --- .../workflows/build/rules-of-workflows.mdx | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/content/docs/workflows/build/rules-of-workflows.mdx b/src/content/docs/workflows/build/rules-of-workflows.mdx index 9af4259837fa67..9a6b0fa4e37da4 100644 --- a/src/content/docs/workflows/build/rules-of-workflows.mdx +++ b/src/content/docs/workflows/build/rules-of-workflows.mdx @@ -449,3 +449,32 @@ export class MyWorkflow extends WorkflowEntrypoint { } ``` + +### Batch multiple Workflow invocations + +When creating multiple Workflow instances, use the [`createBatch`](/workflows/build/workers-api/#createBatch) method to batch the invocations together. This allows you to create multiple Workflow instances in a single request, which will reduce the number of requests made to the Workflows API and increase the number of instances you can create per minute. + + + +```ts +export default { + async fetch(req: Request, env: Env): Promise { + let instances = [{"id": "user1", "params": {"name": "John"}}, {"id": "user2", "params": {"name": "Jane"}}, {"id": "user3", "params": {"name": "Alice"}}, {"id": "user4", "params": {"name": "Bob"}}]; + + // 🔴 Bad: Create them one by one, which is more likely to hit creation rate limits. + for (let instance of instances) { + await env.MY_WORKFLOW.create({ + id: instance.id, + params: instance.params + }); + } + + // ✅ Good: Batch calls together + // This improves throughput. + let instances = await env.MY_WORKFLOW.createBatch(instances); + return Response.json({ instances }) + }, +}; +``` + +