Skip to main content

Scheduled runs

Schedule Hex apps to re-run on a set schedule — hourly, daily, weekly, or monthly intervals.

Scheduled runs do two important things:

  1. Execute the entire project's Logic top to bottom.
    • This means any side effects of running the project (a database write-back, an API call, a webhook ping, etc.) will occur.
  2. Update the cache of the published app, used for the initial state a user sees opening the app.

Scheduled runs may be delayed up to 60 seconds. This is done for reliability at times when many jobs may be scheduled to run simultaneously.

Access scheduling options through the Historical runs tab in the left sidebar. Here you can configure schedules as well as view details about past runs via the run log.

For any scheduled run, you can view the historic state of the app at runtime by selecting the specific run.

You can schedule apps to run on hourly, daily, weekly or monthly intervals. Users on the Team and Enterprise plans can use cron expressions to schedule runs with more customization by choosing the Custom frequency.

When creating a scheduled run, you will have the option to configure notifications for when the scheduled run succeeds or fails, as well as which users will receive those notifications. By default, project Owners will be notified if a scheduled run fails.

In order to receive scheduled run notifications, a user must have App User access or higher to the project. If you attempt to set notifications for a user or user group that does not have access to the project, the user(s) will automatically be granted App User access.

If you turn on notifications for successful runs, you'll also have the option to include a screenshot of the app. When this setting is toggled on, success notifications will include an embedded screenshot of the published app in .png format.

You can create multiple scheduled runs for a given project, each with its own notification settings.


Important: scheduled runs operate on the currently published version of the logic, which may differ from the version you're viewing. Learn more about published versions here.

Scheduled runs and caching

When an app performs a scheduled run, the default state of the published app is updated with the results of the run. If the cache default state option is on, subsequent visitors to the app will see the cached values set during the scheduled run. App users can still re-run the app manually at any time to see freshly generated outputs (with the exception of SQL cells that are cached on a schedule). These manual runs will not update the cache for any other user of the app, and will not persist if the user refreshes the page.

This can be useful for computationally expensive apps that take a long time to run and do not need to be updated multiple times per hour. Regardless of how long the Logic of an app takes, cached results will appear almost instantly.

Scheduled run variable

The built-in hex_scheduled variable is a boolean that evaluates to True while executed as part of a scheduled run. For example, this could be used so that a database write-back is only triggered on a scheduled run, and not as part of an ad hoc usage of an app.

This can be useful for workflows with long-running or computationally expensive query steps, so the app is more responsive for end users. This can be achieved using a similar pattern to:

if hex_scheduled:
## expensive query step
## write results out to a file or database
## read from written file or database

The hex_run_context variable is more granular and allows you to detect the specific run context of the app run. This variable will evaluate to logic, app, scheduled, or api-triggered.

if hex_run_context == "logic":
## something that only needs to happen during a manual Logic run
## something that should happen as part of app or scheduled runs

Files created in scheduled runs

Files created and written to a project's file directory during scheduled jobs or published app sessions are not persisted between scheduled runs. This means that any files written out by a scheduled job cannot be accessed in the Logic View, App Builder, or in future scheduled runs of the project. For example, a file saved using to_csv in a Python cell can only be read back in during the same scheduled run.

If you need to persist files between scheduled runs, we recommend writing the data to an external source, such as your database, S3, or Google Drive. Then, you can read this data back in during future runs of the project, including scheduled runs and published app runs.