Skip to main content

​
Introduction

Background tasks are scheduled workflows that run in the background, independently of any API request or other logic. They’re ideal for recurring operations like data cleanup, notifications, or re-engagement campaigns. Unlike APIs and custom functions, background tasks do not accept inputs or return a response. They are only used to run logic on a schedule.

​
Anatomy

Every XanoScript background task follows a predictable structure. Here’s a quick visual overview of its main building blocks — from declaration at the top to settings at the bottom.

You can find more detail about each section by continuing below.
XanoScript
task reengage_users {
  description = "Looks at the user table for users that haven't logged in for the last 30 days or more, and sends them an email trying to reengage them with the platform"
  stack {
    db.query user {
      search = $db.user.last_login <= ("now"|timestamp_subtract_months:1)
      return = {type: "list"}
    } as $user1
  
    foreach ($user1) {
      each as $item {
        util.send_email {
          api_key = "abc123"
          service_provider = "resend"
          subject = "Hey, where'd you go?"
          message = "We noticed you haven't logged in for a while. Come back and give us another shot?"
          to = $item.email
          bcc = []
          cc = []
          from = "admin@myapp.com"
          reply_to = ""
          scheduled_at = ""
        } as $x1
      }
    }
  }

  schedule {
    events = [{starts_on: 2025-10-01 06:00:00+0000, freq: 604800}]
  }

  tags = ["user actions", "retention"]
  history = {inherit: true}
}

​
Declaration

Every Background Task starts with a declarative header that specifies its type, name, and HTTP verb.
XanoScript
task reengage_users {
description = "Looks at the user table for users that haven't logged in for the last 30 days or more, and sends them an email trying to reengage them with the platform"
active = false
datasource = "test"

}
ElementRequiredDescription
task✅Declares an Background Task primitive.
task_name✅The unique name for the task (e.g., reengage_users).
descriptionnoOptional human-readable description of the task.
activenoWhether the task is active.
datasourcenoSpecifies the datasource to use for this Background Task.

​
Section 1: Stack

The stack block contains the actual logic that will be executed when the Background Task is running.

Hover over this image to see the XanoScript version

The syntax mirrors how you’d configure these functions visually, but expressed textually. The actual behavior is the same — refer to the function’s existing docs for complete details.

Review all available functions and their XanoScript in the function reference

​
Section 2: Schedule

The schedule block contains the schedule in which the Background Task will run on.
You may know this as the ‘Timing’ section in the visual builder.

Hover over this image to see the XanoScript version


The schedule begins with an events array, which contains one or more objects to represent a schedule entry. Each schedule entry contains a starts_on date/time in YYYY-MM-DD HH:MM:SS+TZ format, a freq in seconds which defines the interval between runs, and can also contain an ends_on date/time in YYYY-MM-DD HH:MM:SS+TZ format. If ends_on is not provided, the task will run indefinitely.If you’re not familiar with background tasks in Xano, you can learn more about them here.

​
Section 3: Settings

There are several optional settings that can be configured for a Background Task. These settings are defined at the root level of the Background Task block, after the definition, stack, and schedule blocks. They affect how the task behaves.
SettingTypeRequiredDescription
descriptionstringnoA human-readable description of the Background Task. Appears in the builder and documentation.
tagsarray[string]noA list of tags used to categorize and organize the Background Task in your workspace.
historyobjectnoConfigures version inheritance and history behavior. {inherit: true} allows this Background Task to inherit history settings from the workspace.

​
Detailed Example

Below, you’ll see a complete example of a typical signup Background Task endpoint.
XanoScript
task reengage_users {
  description = "Looks at the user table for users that haven't logged in for the last 30 days or more, and sends them an email trying to reengage them with the platform"
  active = false
  datasource = "test"
  stack {
    db.query user {
      search = $db.user.last_login <= ("now"|timestamp_subtract_months:1)
      return = {type: "list"}
    } as $user1
  
    foreach ($user1) {
      each as $item {
        util.send_email {
          api_key = "abc123"
          service_provider = "resend"
          subject = "Hey, where'd you go?"
          message = "We noticed you haven't logged in for a while. Come back and give us another shot?"
          to = $item.email
          bcc = []
          cc = []
          from = "admin@myapp.com"
          reply_to = ""
          scheduled_at = ""
        } as $x1
      }
    }
  }

  schedule {
    events = [
      {
        starts_on: 2025-10-01 06:00:00+0000
        freq     : 604800
        ends_on  : 2025-10-26 19:51:05+0000
      }
    ]
  }

  tags = ["user actions", "retention"]
  history = {inherit: true}
}

​
What’s Next

Now that you understand how to define Background Tasks in XanoScript, here are a few great next steps:

Explore the function reference

Learn about the built-in functions available in the stack to start writing more complex logic.
https://mintlify.s3.us-west-1.amazonaws.com/xano-997cb9ee/images/vscode.svg

Try it out in VS Code

Use the XanoScript VS Code extension with Copilot to write XanoScript in your favorite IDE.

Learn about Triggers

They work just like your APIs and custom functions, but they run only when certain other events happen, such as new records in a table.
⌘I