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

# Orchestrator

> Run agents on a cron schedule, through the orchestrator of your choice.

Recurring runs are delegated to an **orchestrator**. Two are supported, and they are
interchangeable: the client for each implements the same method surface, so nothing in
the calling code changes when you switch.

| `ORCHESTRATOR` | Backend                         | Notes                                             |
| -------------- | ------------------------------- | ------------------------------------------------- |
| `mage`         | [Mage AI](https://www.mage.ai/) | **the default** — used when the variable is unset |
| `th2etl`       | [th2etl](/ecosystem/th2etl)     | the in-house replacement                          |

<Note>
  Only these two values change behavior. Anything else is read as an unrecognized
  setting and falls back to `mage` — there is no third backend.
</Note>

<Warning>
  The setting is read by the listing endpoints too, not only when a schedule is created.
  A deployment that flips the flag without restarting keeps reading the previous
  orchestrator, and the runs created on the new one never appear.
</Warning>

<Frame caption="The orchestrator screen: one row per agent, with its model, its schedule and a manual trigger.">
  <img src="https://mintcdn.com/thaink2-445e19b2/01sXtdZdZRmlIMtW/images/orchestrator.jpg?fit=max&auto=format&n=01sXtdZdZRmlIMtW&q=85&s=136a07505ba2f28777a632e73af1f243" alt="Orchestrator screen listing agents with their model, schedule and run actions" width="1600" height="1040" data-path="images/orchestrator.jpg" />
</Frame>

## Scheduling a run

```json theme={null}
POST /api/adk/schedule_run
{
  "agent_id": "agent42",
  "user_id": "user@example.com",
  "session_id": "session_scheduled",
  "new_message": {
    "role": "user",
    "parts": [{ "text": "Generate the daily report" }]
  },
  "schedule_interval": "@daily",
  "start_time": "2026-03-10T08:00:00"
}
```

### Interval shortcuts

| Preset                      | Cron                |
| --------------------------- | ------------------- |
| `@hourly`                   | `0 * * * *`         |
| `@daily` — also `@midnight` | `0 0 * * *`         |
| `@weekly`                   | `0 0 * * 0`         |
| `@monthly`                  | `0 0 1 * *`         |
| Custom                      | e.g. `*/15 * * * *` |

Mage accepts the `@interval` shortcuts directly. The th2etl client translates them into
five-field cron expressions before creating the trigger, so the same request body works
against either backend.

## Managing schedules and runs

| Method | Endpoint                                                      | Description                   |
| ------ | ------------------------------------------------------------- | ----------------------------- |
| GET    | `/api/pipelines`                                              | List pipelines                |
| POST   | `/api/pipelines/agents/triggers`                              | Create a trigger for an agent |
| GET    | `/api/pipelines/{pipeline_uuid}/schedules`                    | List an agent's schedules     |
| PUT    | `/api/pipelines/{pipeline_uuid}/schedules/{schedule_id}`      | Update a schedule             |
| GET    | `/api/pipelines/{pipeline_uuid}/schedules/{schedule_id}/runs` | List a schedule's runs        |
| GET    | `/api/pipelines/runs/{run_id}`                                | Get one run                   |
| GET    | `/api/pipelines/runs/{run_id}/logs`                           | Get a run's logs              |
| PUT    | `/api/pipelines/runs/{run_id}/cancel`                         | Cancel a run                  |

The endpoints keep the `pipelines` naming from the Mage era. They are orchestrator
agnostic: the same calls reach th2etl when the flag is set.

## What changes between the two

The mapping matters if you inspect the orchestrator directly rather than through this
API.

|                       | Mage               | th2etl                                                                   |
| --------------------- | ------------------ | ------------------------------------------------------------------------ |
| Unit per agent        | a pipeline trigger | one scheduler, **named after the `agent_id`**                            |
| Schedule identifier   | an integer id      | the scheduler **name**                                                   |
| Per-trigger variables | trigger variables  | the scheduler's `variables`, injected into the run context on every fire |
| Ad-hoc trigger        | trigger a run      | `POST /schedulers/{name}/run`                                            |

<Note>
  Identifiers are opaque to callers — read one from a listing and pass it back. Do not
  compare them numerically: Mage ids are integers while th2etl uses names, and a
  numeric comparison against a th2etl id silently fails to match.
</Note>

## Configuration

See [Configuration](/configuration) for the variables each orchestrator needs. When
`ORCHESTRATOR` is unset, the server talks to Mage — so a deployment that means to use
th2etl must set it explicitly.