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 }) + }, +}; +``` + + diff --git a/src/content/docs/workflows/build/workers-api.mdx b/src/content/docs/workflows/build/workers-api.mdx index ca3e3e80c07a5e..37b9f83ef9e141 100644 --- a/src/content/docs/workflows/build/workers-api.mdx +++ b/src/content/docs/workflows/build/workers-api.mdx @@ -266,6 +266,30 @@ export default { } ``` +### createBatch + +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/reference/limits/). + +* 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: "id-abc123", params: { "hello": "world-0" } }, + { id: "id-def456", params: { "hello": "world-1" } }, + { id: "id-ghi789", params: { "hello": "world-2" } } +]; +let instances = await env.MY_WORKFLOW.createBatch(listOfInstances); +``` + +Returns an array 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.