Bubble Docs
Comment on page

Scheduling API Workflows

API Workflows can be triggered or scheduled internally in your app
Help us improve this article
This article is part of a significant update to the Bubble manual and your feedback is critical to our efforts to continuously enhance our written documentation. We would greatly appreciate if you could take a moment to let us know your thoughts on the quality of it. Thank you for your support! Give feedback on this article
While the Workflow API is useful for building workflows that can be exposed and triggered by external applications and systems, API Workflows can also be used to schedule workflows in your application.

Scheduled API workflow use cases

There are many use cases where scheduling an API Workflow is a better alternative than running a workflow on the page.
  • When you need to schedule an action in the future, such as:
    • Sending an email X number of hours after a User signs up
    • Send a reminder X number of days before an event
    • Terminate a trial one month after it has started
  • Schedule recurring Events, such as
    • Sending a weekly newsletter
    • Calculate and save statistics or aggregations
    • Delete redundant data to clean up the database
  • Performing complex Workflows, such as:
    • Actions that involve complex searches and filtering
    • Workflows that contain a long list of actions that can take some time to complete
  • Looping Workflows, to:
    • Make changes to a list of Things one-by-one
    • Run actions that depend on a previous cycle to complete
  • Set up cascading Workflows, such as:
    • Deleting Things in your database that are connected to other Things that also need to be deleted or updated

How to schedule an API Workflow

After you have built the API Workflow you want to trigger, you schedule it to run at the current date-time or in the future by using the action Schedule API Workflow.
Scheduling an API Workflow will prompt you to set a date and time for when to run, as well as specify any parameters you set up when the API Workflow was created.
You pick the API workflow you want to schedule and define the time of the scheduling. You'll be prompted to fill the different parameters that have been defined at the API workflow level.
Note that if you schedule an API workflow in the past, it will trigger immediately.

Schedule an API Workflow on a list of Things

You can also schedule an API workflow on a list of Things. This way you are scheduling one workflow per entry in the list.
For example, if you want to run a workflow on 20 users, you can use the Schedule API Workflow on a list of things action to schedule 20 separate API Workflows. You can then set up that workflow to perform actions on one user at a time.
While this can be used to run a given workflow separately on each item in a list, it's not technically looping – scheduling an API Workflow on a list will schedule one workflow per item, but it will not wait for one to finish before it moves on to the next.
If you are looking to create an API Workflow that loops over entries in a list sequentially, you can use Recursive Workflows instead of Schedule API Workflow on a list.
For performance reasons, Bubble may space in time the different executions of the workflows.
The scheduling of a list of API Workflows can time out if the list is too long. For lists that are longer than a 100 items we recommend using Recursive API Workflows instead. Since they are scheduled sequentially instead of all at once, you can avoid timing out.
To schedule an API Workflow on a list, make sure to define your endpoint with a parameter for a particular Data Type.
You can define what kind of Data Type you want to schedule the list of Workflows on. In the example above we've set up a parameter with the User data type.
Then, when you schedule the API workflow on a list, you'll choose the type of thing, the list to run on, and for the parameter you'll be able to choose "this thing".
By setting the Type of things to the Data Type we created a parameter for, we can run the workflow once for every User we find in the Search for user list result.
The API workflow well then run in the context of this thing for each thing in the list.

Canceling a scheduled workflow

The Bubble editor also retains a list of scheduled API Workflows where you can view, pause and cancel individual or all scheduled workflows. See more in the article below:
Whenever you schedule an API Workflow Bubble generates a unique ID for that specific instance. The Schedule API Workflow returns that ID so that you can reference that in a later step in the same workflow:
Scheduling an API Workflow returns a unique ID that you can use in the next step. In this example we're saving the ID on the Current User-
You can use this ID to cancel the API Workflow at any time before it is scheduled to run by using the Cancel a scheduled API Workflow action.
To cancel a list of scheduled Workflows you can use the Cancel a list of scheduled API Workflows action.