Scheduled runs

Set up your Hex apps to automatically run on a schedule. Scheduled runs can also be used to update published results, and trigger app notifications.

info

• Scheduled runs are available on the Team and Enterprise plans.
• The Professional plan is limited to 1 scheduled run per project and does not include Slack notifications or custom schedules.
• Users with Can edit or higher project permissions can manage all scheduled runs on a project.
• Users with Can view project permissions and the Editor role can create a maximum of one scheduled run per project.

Hex apps can be configured to be run on a schedule that suits your use case, with a maximum frequency of hourly.

When a scheduled run is triggered, the cells required by the app are run, providing a way to automate code execution. Scheduled runs can also be used to update the published results, and to trigger app notifications.

tip

Your app needs to be published before a scheduled run can be setup. Scheduled runs will always run the currently published version, rather than the draft version.

The scheduled runs for a project can be accessed in two different UI locations:

• Published app: Via the Scheduled runs & Notifications item in the three-dot menu in the top right-hand corner of the app.
• Notebook view: The Scheduled runs tab in the left sidebar

This sidebar contains details of the currently configured scheduled runs, your notifications tied to the scheduled run, and a log of past scheduled runs.

Create a scheduled run

To create a scheduled run, visit the Scheduled runs sidebar in either the published app or the notebook, and select + Add. You can schedule apps to run on hourly, daily, weekly or monthly intervals.

Users on the Team and Enterprise plan also have the option of using a cron expression to define a schedule.

Users with Can edit permissions can multiple scheduled runs per project.

Users with Can view permissions, and the Editor role can create up to one scheduled run per project, with a maximum frequency of daily.

Note: scheduled runs may be delayed up to five minutes. This is done for reliability at times when many jobs may be scheduled to run simultaneously.

Update published results

If your app is set to show results from a previous run, users with Can edit permission can leverage scheduled runs to update the results a user sees when they open the app.

Runs that update the published results are marked in the scheduled runs list with a refresh icon.

By default, scheduled runs created by users with Can edit permission will update the published results.

To change whether a scheduled run updates published results, a user with Can edit permission should:

1. Select the scheduled run from the sidebar
2. Click the pencil icon to edit the schedule
3. Toggle the Update published results setting

In contrast, scheduled runs created by users with Can view permissions will never update the published results. Users with Can view permission cannot change this setting.

Scheduled runs & SQL caching

By default, scheduled runs created by users with Can edit permission will not use cached SQL results, and instead run the queries from scratch, writing the latest query results to the SQL cache.

To change whether a scheduled run uses cached SQL results, a user with Can edit permission should:

1. Select the scheduled run from the sidebar
2. Click the pencil icon to edit the schedule
3. Toggle the Update published results setting

See above section for a product image

Scheduled runs created by users with Can view permissions will always use cached SQL results to reduce warehouse loads. Users with Can view permission cannot change this setting.

Send notifications

Scheduled runs can be used as triggers for two types of notifications:

• Subscriptions: Deliver a link to an app when a scheduled run completes, or be notified if the scheduled run errors.
• Conditional notifications: Get notified after a scheduled run, only if a condition is met.

Learn more about configuring app notifications.

Scheduled runs & input values

Scheduled runs always execute with the default values for inputs. If you need to execute a project with the non-default values for inputs, consider using the RunProject API endpoint instead, which allows you to specific custom input values using the inputs key.

Detecting scheduled runs in code

Hex provides two built-in variables that can be used to determine if a run is happening as part of a scheduled run:

• hex_scheduled (boolean): returns True when the project is being executed as part of a scheduled run.
• hex_run_context (enum): returns 'scheduled' when the project is being executed as part of a scheduled run. Other values are: 'logic', 'app', 'api-triggered'.

Detecting when code is being executed as part of a scheduled run can be useful certain operations should happen during scheduled runs only. For example, this could be used so that a write to an external service is only triggered on a scheduled run, and not as part of an ad hoc usage of an app.

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

if hex_run_context == "scheduled":
    ## something that only needs to happen during a scheduled run
else:
    ## something else

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 Notebook 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.

Manage scheduled runs in a workspace

Workspace admins can view all scheduled runs in a workspace from the Admin panel. Learn more about managing scheduled runs.

tip

Consider setting up auto-archive rules to help manage scheduled runs. Scheduled runs are disabled on archived projects.