Tasks 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.

The bot must have Tasks enabled. Set tasks: true via the Bot Management API update endpoint — the flag kept its original name.

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 for the method mapping.

Create a task

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

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

GET /v1/bot/tasks/read?project_id=…&bot_id=…&task_id=…

await client.fetchTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });

List tasks

GET /v1/bot/tasks/readall?project_id=…&bot_id=…

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

PUT /v1/bot/tasks/update

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:

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

POST /v1/bot/tasks/enable
POST /v1/bot/tasks/disable

await client.enableTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });
await client.disableTask({ bot_id: 'bot-uuid', task_id: 'task-uuid' });

Trigger manually

POST /v1/bot/tasks/trigger

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

DELETE /v1/bot/tasks/delete?project_id=…&bot_id=…&task_id=…

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

DELETE /v1/bot/tasks/logs/delete?project_id=…&bot_id=…&run_id=…

await client.deleteTaskLog({ bot_id: 'bot-uuid', run_id: 'run-uuid' });

Logs and stats

GET /v1/bot/tasks/logs?project_id=…&bot_id=…
GET /v1/bot/tasks/stats?project_id=…&bot_id=…

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.

Getting Started

Choose Your Path

Providers & Models

Overview

Create a task

Parameters

Schedule shapes

Example

Get a task

List tasks

Update a task

Schedule frequency

Enable / disable

Trigger manually

Delete a task

Run statuses

Delete a run

Logs and stats

Next steps

Tasks for creators

Bot Management

​Overview

​Create a task

​Parameters

​Schedule shapes

​Example

​Get a task

​List tasks

​Update a task

​Schedule frequency

​Enable / disable

​Trigger manually

​Delete a task

​Run statuses

​Delete a run

​Logs and stats

​Next steps

Tasks for creators

Bot Management

Overview

Create a task

Parameters

Schedule shapes

Example

Get a task

List tasks

Update a task

Schedule frequency

Enable / disable

Trigger manually

Delete a task

Run statuses

Delete a run

Logs and stats

Next steps