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

# Tasks API

> Create and manage autonomous agent schedules via the API

## Overview

The Tasks API lets you programmatically create, manage and monitor autonomous agent runs. A task
executes a prompt on a schedule, uses the agent's connected tools, and can notify users — all
without anyone present.

> [!NOTE]
>
> The bot must have Tasks enabled. Set `tasks: true` via the
> [Bot Management API](/docs/sdk/core/bot-management.md) update endpoint — the flag kept its original name.

> [!WARNING]
>
> **Replaces the Heartbeat API.** Heartbeats and scheduled tasks were one engine written twice and
> have merged. `/v1/bot/heartbeat/*` is gone; the endpoints below take its place, and
> `heartbeat_id` is now `task_id`. SDK users: see the [6.0.0 changelog](/docs/changelog.md) for the method
> mapping.

## Create a task

```bash theme={null}
POST /v1/bot/tasks/create
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | Yes | Project UUID |
| `bot_id` | string | Yes | Bot UUID |
| `name` | string | Yes | Short name, as it appears on the board |
| `prompt` | string | Yes | The instruction the agent executes each run |
| `schedule_type` | string | No | `interval`, `daily`, `weekly`, `cron` or `once` (default: `interval`) |
| `schedule_config` | object | No | Shape depends on `schedule_type` — see below |
| `description` | string | No | Why this task exists; shown on the card |
| `enabled` | boolean | No | Whether it is live (default: `true`) |
| `timezone` | string | No | Timezone for scheduling (default: `UTC`) |
| `max_executions` | number | No | Disable the task after this many runs |
| `max_consecutive_errors` | number | No | Auto-pause after this many failures (default: 5) |
| `member_id` | string | No | Which project member owns the task |
| `chat_mode` | string | No | `ask`, `edit` or `plan` |

### Schedule shapes

| `schedule_type` | `schedule_config` |
| - | - |
| `interval` | `{ "interval_minutes": 60 }` |
| `daily` | `{ "time": "09:00" }` |
| `weekly` | `{ "day": 1, "time": "09:00" }` — day 1 = Monday |
| `cron` | `{ "cron": "0 9 * * 1-5" }` |
| `once` | `{ "scheduled_at": "2026-09-01T09:00:00Z" }` |

### Example

```javascript theme={null}
const client = new BoostGPT({ key: 'YOUR_API_KEY', project_id: 'PROJECT_UUID' });

await client.createTask({
  bot_id: 'bot-uuid',
  name: 'Triage support tickets',
  prompt: 'Check for new support tickets and summarize the urgent ones',
  cron_pattern: '0 9 * * 1-5',        // weekdays at 9am
  timezone: 'America/New_York'
});
```

`cron_pattern` is a shorthand the SDK translates to `schedule_type: 'cron'`. Pass `schedule_type`
and `schedule_config` directly for anything else.

## Get a task

```bash theme={null}
GET /v1/bot/tasks/read?project_id=…&bot_id=…&task_id=…
```

```javascript theme={null}
await client.fetchTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });
```

## List tasks

```bash theme={null}
GET /v1/bot/tasks/readall?project_id=…&bot_id=…
```

```javascript theme={null}
await client.fetchTasks({ bot_id: 'bot-uuid' });
```

Recurring tasks come back with `state: null` — they are schedules, not board cards. One-shot tasks
carry a `state` of `backlog`, `todo`, `in_progress`, `review` or `done`.

## Update a task

```bash theme={null}
PUT /v1/bot/tasks/update
```

```javascript theme={null}
await client.updateTask({
  bot_id: 'bot-uuid',
  task_id: 'task-uuid',
  prompt: 'Check for new tickets and summarize the urgent ones',
  schedule_config: { interval_minutes: 60 },
  enabled: true
});
```

Subject to the same frequency floor as creation — see below.

## Schedule frequency

Every plan enforces a **minimum interval of 15 minutes**. It is an infrastructure limit rather than
a tier: credits are what meter automation, and the floor exists so a schedule cannot fire faster
than a run can finish. A schedule below it is refused:

```javascript theme={null}
const { err } = await client.createTask({
  bot_id: 'bot-uuid',
  name: 'Too eager',
  prompt: 'Check the inbox',
  schedule_type: 'interval',
  schedule_config: { interval_minutes: 1 }
});

err.status;   // 400
err.code;     // 'schedule_too_frequent'
err.message;  // "The shortest interval on this plan is 15 minutes; 1 was requested."
```

Cron is measured the same way — the shortest gap between two fires has to clear the floor, so
`* * * * *` is refused and `0 9 * * 1-5` is not.

## Enable / disable

```bash theme={null}
POST /v1/bot/tasks/enable
POST /v1/bot/tasks/disable
```

```javascript theme={null}
await client.enableTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });
await client.disableTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });
```

## Trigger manually

```bash theme={null}
POST /v1/bot/tasks/trigger
```

```javascript theme={null}
await client.triggerTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });
```

A card only runs while it is `in_progress`; triggering one parked in `backlog` records a skip with
the reason rather than running it.

## Delete a task

```bash theme={null}
DELETE /v1/bot/tasks/delete?project_id=…&bot_id=…&task_id=…
```

```javascript theme={null}
await client.deleteTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });
```

Deleting removes the task's queued schedule as well as the row.

## Run statuses

Each run in the log carries a `status`:

| status | meaning |
| - | - |
| `success` | The run finished. |
| `error` | The run started and failed. Consecutive errors eventually pause the schedule. |
| `skipped` | The run was declined before starting; `reason` says why. |
| `interrupted` | The run was killed mid-flight, normally by a deploy or restart. Deliberately not counted as an error, so a restart cannot walk a schedule into its error threshold. |

Common `reason` values on a skip: `already_running` (the previous fire has not finished),
`schedule_clamped` (the schedule was below the plan floor and was slowed to it), `no_credits`,
`outside_active_hours`, `max_executions_reached`, `assigned_to_member`, `bot_offline`.

## Delete a run

```bash theme={null}
DELETE /v1/bot/tasks/logs/delete?project_id=…&bot_id=…&run_id=…
```

```javascript theme={null}
await client.deleteTaskLog({ bot_id: 'bot-uuid', run_id: 'run-uuid' });
```

## Logs and stats

```bash theme={null}
GET /v1/bot/tasks/logs?project_id=…&bot_id=…
GET /v1/bot/tasks/stats?project_id=…&bot_id=…
```

```javascript theme={null}
await client.fetchTaskLogs({ bot_id: 'bot-uuid' });
await client.fetchTaskStats({ bot_id: 'bot-uuid' });
```

Run records carry `status` (`success`, `error` or `skipped`), a `reason` when skipped,
`duration_ms` and `tokens_used`. A successful run's full exchange lives in the conversation it ran
in — the run record is what tells you about the runs that did *not* happen.

## Next steps

> [card] [Tasks for creators](/docs/mira/tasks.md)
>
> The board, autonomy rungs, and the weekly site review

> [card] [Bot Management](/docs/sdk/core/bot-management.md)
>
> Enabling tasks on an agent


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.