> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Scheduled Tasks run a target — a GraphQL operation, a gateway route, or an external API — on a cron schedule or once at a set time, with retries, overlap control, and a full run history.

Scheduled Tasks let a project run work automatically — on a repeating cron schedule or once at a future time. Each task is a **trigger**: a schedule plus a target to call and the credential to call it with. Archie fires the target on schedule, retries on failure, and records every run.

Use them for nightly rollups, reminder emails, data syncs, cache warming, or any job that should run without someone clicking a button.

Open a project, switch to the Backend Console, and select **Scheduled Tasks**.

## Core concepts

<CardGroup cols={2}>
  <Card title="Trigger" icon="clock">
    One scheduled task: a name, a schedule, a target, and an execution credential. Triggers have a lifecycle — active, paused, completed, or archived.
  </Card>

  <Card title="Schedule" icon="calendar-days">
    When the trigger fires. Either a recurring cron expression in a timezone, or a one-off run at a specific date and time.
  </Card>

  <Card title="Target" icon="crosshairs">
    What the trigger calls: a GraphQL operation, a REST or Custom API gateway route, or an external HTTPS API.
  </Card>

  <Card title="Execution" icon="list-check">
    One run of a trigger. Every fire — scheduled or manual — produces an execution record with its status, timing, and response.
  </Card>
</CardGroup>

## How it works

Scheduled Tasks span three parts of the platform. Knowing the path helps when you're debugging a task that isn't firing.

<Steps>
  <Step title="You configure the task in the Backend Console">
    The **Scheduled Tasks** UI in the frontend collects the schedule, target, and options, and sends a GraphQL mutation to your project's backend API.
  </Step>

  <Step title="The backend validates and forwards it">
    The backend API resolves your **project and environment from the auth token** — never from the request body — and forwards the call to the scheduler service. Because the tenant comes from the token, one project can't create or read another's tasks.
  </Step>

  <Step title="The scheduler service stores and runs it">
    The scheduler service persists the trigger, computes the next fire time, and enqueues the run. When the time comes it dispatches the target with your stored credential, applies retries and the overlap rule, and records the execution.
  </Step>
</Steps>

Everything you do in the UI — create, edit, pause, run now, browse history — is a GraphQL operation against the backend API, so the same actions are available programmatically. See [the API reference](/docs/features/backend/scheduled-tasks/run-history#graphql-api) for the operation names.

## The trigger lifecycle

A trigger is always in one of four **stored** states:

| Status        | Meaning                                                 |
| ------------- | ------------------------------------------------------- |
| **Active**    | Scheduled and firing on time.                           |
| **Paused**    | Kept but not firing. Resume any time with **Enable**.   |
| **Completed** | A one-off task that has fired its single run. Terminal. |
| **Archived**  | Retired. Kept for history but never fires again.        |

**Failing** is not a stored state — it's a derived health signal. An active trigger whose recent runs all failed is surfaced as failing, with its consecutive-failure count and last success and failure times, so a broken task stands out without changing its status.

## What a target can be

| Target            | What it calls                                                                                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GraphQL**       | A GraphQL operation you write inline — query or mutation, with variables — against your project's API.                                                                        |
| **REST**          | A [REST API](/docs/features/backend/rest-api-explorer/overview) route on your project.                                                                                             |
| **Custom API**    | A [Custom API](/docs/features/backend/app-services/custom-apis) gateway route.                                                                                                     |
| **External REST** | An arbitrary public `https://` API. Requests are screened by an anti-SSRF guard — only public hosts are allowed; private, loopback, and cloud-metadata addresses are blocked. |

The first three call **internal platform artifacts** by reference, so they stay inside your project's auth and gateway model. External REST is the only target that leaves the platform, which is why it's restricted to public HTTPS hosts.

## Execution credential

Every trigger carries an **execution credential** — the `Authorization` value (for example `Bearer <token>`) used when it dispatches. Create a role-bound [API key](/docs/features/backend/settings/api-keys) with exactly the permissions the task needs, and give it to the trigger.

The credential is **write-only**: it's stored encrypted and never returned by the API or shown again in the UI. When you edit a task, leaving the credential blank keeps the stored one.

<Warning>
  If the API key behind a task is revoked or expires, its runs fail — an execution is recorded with an identity-revoked status. Rotate the key on the task before revoking the old one.
</Warning>

## Per-environment

Scheduled Tasks are scoped to an [environment](/docs/features/backend/environments/overview). A task defined in `master` is separate from one in another environment, each with its own schedule, credential, and run history. Create the tasks an environment needs in that environment.

## Where to go next

<CardGroup cols={2}>
  <Card title="Create a task" icon="plus" href="/docs/features/backend/scheduled-tasks/creating-a-task">
    Walk through the schedule, target, and execution options step by step.
  </Card>

  <Card title="Run history & monitoring" icon="chart-line" href="/docs/features/backend/scheduled-tasks/run-history">
    Read execution statuses, run a task on demand, and manage its lifecycle.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between a Scheduled Task and a Custom Function?">
    A [Custom Function](/docs/features/backend/custom-functions/overview) is code you write and deploy. A Scheduled Task is a schedule that calls a target — which can be a GraphQL operation, a gateway route, or an external API. A task can call an endpoint backed by a custom function, but the task itself is scheduling and dispatch, not code.
  </Accordion>

  <Accordion title="Can a task run every minute / on a complex schedule?">
    Yes — any cron expression is accepted, in the timezone you choose. You can also write the schedule in plain language and have Archie resolve it to a cron expression for you. See [Creating a task](/docs/features/backend/scheduled-tasks/creating-a-task).
  </Accordion>

  <Accordion title="Are tasks copied when I branch an environment?">
    Tasks live per-environment. Create the tasks each environment needs in that environment; credentials in particular are never shared across environments.
  </Accordion>

  <Accordion title="Can two runs of the same task overlap?">
    That's up to the task's overlap rule — skip the new fire, queue it behind the running one, or allow concurrent runs. See [Creating a task](/docs/features/backend/scheduled-tasks/creating-a-task#execution-options).
  </Accordion>
</AccordionGroup>