Skip to main content

Run a function on a schedule

Attach one or more cron schedules to a function so it runs without being called.

Prerequisites#

  • An existing function in an app.
  • An organization owner or admin account, or another cloud user with access to the site.

Add a schedule#

Schedules are written through the function itself.

PATCH/api/apps/$TARUVI_APP_SLUG/functions/$FUNCTION_SLUG/

Headers

Authorization
Api-Key $TARUVI_API_KEY
Content-Type
application/json

Request body

{
  "schedules": [
    {
      "cron_expression": "0 9 * * 1",
      "schedule_params": {
        "report": "weekly"
      },
      "is_active": true
    }
  ]
}
View cURL
curl -X PATCH "$TARUVI_SITE_URL/api/apps/$TARUVI_APP_SLUG/functions/$FUNCTION_SLUG/" \
  -H "Authorization: Api-Key $TARUVI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "schedules": [
    {
      "cron_expression": "0 9 * * 1",
      "schedule_params": {
        "report": "weekly"
      },
      "is_active": true
    }
  ]
}
JSON

200Saves the schedules, but responds 200 with status error and No changes detected, version unchanged, because schedules don't create a version. Read the function back to confirm. Each schedule creates its own periodic task.

Schedules aren't versioned, so a request that changes only schedules saves them but responds 200 with status: "error" and No changes detected, version unchanged. Read the function back to confirm the schedule.

Write the cron expression#

A schedule uses a five-part cron expression:

minute  hour  day-of-month  month  day-of-week
ExpressionRuns
0 9 * * 1Every Monday at 09:00
*/15 * * * *Every fifteen minutes
0 0 1 * *At midnight on the first of each month
30 6 * * 1-5Weekdays at 06:30

An expression with the wrong number of parts, or one cron cannot parse, is rejected when you save.

Give each schedule its own parameters#

A function can carry several schedules, each with its own expression and its own schedule_params. Those parameters reach the function as params, exactly as if a caller had supplied them.

This lets one function serve several jobs — a daily summary and a weekly summary, say — without duplicating the code:

{
  "schedules": [
    {"cron_expression": "0 7 * * *", "schedule_params": {"period": "daily"}, "is_active": true},
    {"cron_expression": "0 8 * * 1", "schedule_params": {"period": "weekly"}, "is_active": true}
  ]
}

Turn a schedule off#

Set is_active to false on the schedule. An inactive schedule stays on the function and doesn't fire; no run or record is created. Use this in preference to deleting a schedule you may want back.

Deactivating the function doesn't turn its schedules off. To stop scheduled runs, set each schedule's is_active to false, in the same request if you also deactivate the function.

Deleting the function deletes its schedules.

Understand how a scheduled run differs#

Scheduled runs are not the same as calls to the execute endpoint, in three ways that matter:

  • They run as the function's creator, not as whoever set up the schedule. If that user's permissions change, the scheduled run's reach changes with them.
  • Filter conditions do not apply. They are evaluated only for event-triggered executions, so a schedule always runs.
  • They are always asynchronous. There is no caller waiting, so the result is collected from the invocation record rather than returned.

Each scheduled run creates an invocation record with a trigger type of schedule, which is how you tell scheduled activity from API traffic.

Verify#

Wait for the next scheduled time, then check the function's runs. A record with trigger type schedule confirms the schedule fired.

To test the logic without waiting, execute the function directly with the same parameters the schedule supplies.