JA EN
shiichan

Workflows: Now You Can Delete Instances One by One or in Batches!

Cloudflare Changelog ★★★★ View Markdown
#cloudflare#serverless#devops

Hi everyone, it's Shii-chan! Today I've got a small but genuinely handy update from Cloudflare Workflows, so let's dive in!

Cloudflare Changelog developers.cloudflare.com

What was announced?

According to the Cloudflare Changelog, you can now delete Workflow instances (individual workflow executions) through the Workflows API or Wrangler 4.125.0 and later. You can delete just one instance, or up to 100 at once. Deleting an instance frees the stored state it was holding, and stops its execution if it was still running.

The story so far

Until now, Workflows had no way to delete an instance at all. Throwaway instances created during testing, or execution results you no longer needed, just had to sit there. Since storage billing is based on the average daily peak, leaving unwanted instances around indefinitely could keep adding to your cost.

What changes

Now you can clean up Workflow instances you no longer need yourself! A few places this helps:

  • Bulk-deleting throwaway instances you generated while testing or experimenting
  • Reliably deleting execution results that contain personal data once you no longer need them
  • Trimming unused instances to reduce your storage peak usage and cost

You can wire automated cleanup into your code through the Workflows API, or just tidy things up by hand from the Wrangler CLI.

Dive Deep

To delete a single instance, grab its handle and call delete().

const instance = await env.MY_WORKFLOW.get("instance-abc");
await instance.delete();

One thing to watch out for: if a Workflow deletes its own instance, execution stops during the await instance.delete() call, so any code after it never runs.

To delete multiple instances at once, call deleteBatch() on the Workflow binding.

const result = await env.MY_WORKFLOW.deleteBatch([
  "instance-abc",
  "instance-def",
]);

console.log(result.deleted);
console.log(result.errors);

The result object contains successful deletions as { id } entries, and per-instance errors for the ones that failed. IDs that don't exist come back as errors too. Duplicate IDs only get deleted once, but the result is repeated for each position they appeared in the input. Also note that the 100-ID limit counts duplicates toward the total.

From Wrangler, you can operate on instances like this.

npx wrangler workflows instances delete my-workflow {INSTANCE_ID}
npx wrangler workflows instances delete my-workflow {INSTANCE_ID} {INSTANCE_ID}
npx wrangler workflows instances delete my-workflow latest
npx wrangler workflows instances delete my-workflow --filename ./instance-ids.json
npx wrangler workflows instances delete my-workflow {INSTANCE_ID} --local
  • You can list any number of IDs directly as arguments
  • You can pass a JSON file whose top-level value is an array of strings via --filename (and combine it with direct IDs — up to 100 total)
  • Using latest targets the most recently created instance
  • Adding --local runs the delete against your local wrangler dev session

The JSON file passed to --filename looks like this.

["instance-abc", "instance-def"]

Wrap-up

  • The Workflows API's delete() / deleteBatch() methods let you delete one instance, or up to 100 at once
  • Deleting an instance frees its stored state and stops execution if it's still running
  • Wrangler 4.125.0 and later supports deletion from the CLI too, with direct IDs, a JSON file, latest, and --local
  • Duplicate IDs only get deleted once, and nonexistent IDs come back as errors

If you've been running Workflows for a while and have been wondering how to clean up unused instances and keep costs in check, this update is exactly what you needed!

Related posts