Heartbeat API

Overview

The Heartbeat API lets you programmatically create, manage, and monitor autonomous agent schedules. Agents with heartbeat enabled run on a timer, execute prompts, use connected tools, and can notify users — all without human interaction.

Before using the Heartbeat API, the bot must have heartbeat enabled. Set heartbeat: true via the Bot Management API update endpoint.

Configure a Heartbeat

Create or update a heartbeat configuration for a bot.

POST /v1/bot/heartbeat/configure

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`bot_id`	string	Yes	Bot UUID
`prompt`	string	Yes	The instruction the agent executes each run
`cron_pattern`	string	No	Cron expression for scheduling (e.g., `0 9 * * 1` for every Monday at 9am)
`enabled`	boolean	No	Whether the heartbeat is active (default: `false`)
`timezone`	string	No	Timezone for scheduling (default: `UTC`)
`credit_budget`	number	No	Max credits per billing period (`null` = unlimited)
`max_consecutive_errors`	number	No	Auto-pause after this many consecutive failures (default: 5)
`member_id`	string	No	Subscriber member ID (for subscriber-specific heartbeats)

Example

const response = await fetch('https://api.boostgpt.co/v1/bot/heartbeat/configure', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    project_id: 'proj_abc123',
    bot_id: 'bot_xyz789',
    prompt: 'Check for new support tickets and summarize any urgent ones',
    cron_pattern: '0 9 * * 1,2,3,4,5',
    enabled: true,
    timezone: 'America/New_York',
    credit_budget: 100
  })
});

const { heartbeat } = await response.json();

Response

{
  "heartbeat": {
    "uuid": "hb_abc123",
    "bot_id": 1,
    "prompt": "Check for new support tickets and summarize any urgent ones",
    "cron_pattern": "0 9 * * 1,2,3,4,5",
    "enabled": 1,
    "timezone": "America/New_York",
    "credit_budget": 100,
    "credits_used": 0,
    "execution_count": 0,
    "error_count": 0,
    "max_consecutive_errors": 5,
    "created_at": "2026-02-12T12:00:00Z",
    "updated_at": "2026-02-12T12:00:00Z"
  }
}

List Heartbeats

Get all heartbeat configurations for a bot.

GET /v1/bot/heartbeat/readall?project_id=proj_abc123&bot_id=bot_xyz789

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`bot_id`	string	Yes	Bot UUID
`member_id`	string	No	Filter by subscriber member ID

Response

{
  "heartbeats": [
    {
      "uuid": "hb_abc123",
      "prompt": "Check for new support tickets...",
      "cron_pattern": "0 9 * * 1,2,3,4,5",
      "enabled": 1,
      "last_status": "success",
      "execution_count": 42,
      "error_count": 0
    }
  ]
}

Get a Heartbeat

Get a single heartbeat configuration by its UUID.

GET /v1/bot/heartbeat/read?project_id=proj_abc123&bot_id=bot_xyz789&heartbeat_id=hb_abc123

Enable a Heartbeat

Activate a heartbeat so it starts running on its schedule.

POST /v1/bot/heartbeat/enable

{
  "project_id": "proj_abc123",
  "bot_id": "bot_xyz789",
  "heartbeat_id": "hb_abc123"
}

Disable a Heartbeat

Pause a heartbeat without deleting its configuration.

POST /v1/bot/heartbeat/disable

{
  "project_id": "proj_abc123",
  "bot_id": "bot_xyz789",
  "heartbeat_id": "hb_abc123"
}

Trigger a Heartbeat

Manually trigger a single heartbeat execution for testing. The heartbeat does not need to be enabled.

POST /v1/bot/heartbeat/trigger

{
  "project_id": "proj_abc123",
  "bot_id": "bot_xyz789",
  "heartbeat_id": "hb_abc123"
}

Response

{
  "result": {
    "status": "success",
    "response": "I checked the support queue and found 3 new tickets...",
    "duration_ms": 4523,
    "tokens_used": 1250,
    "credits_charged": 2
  }
}

Delete a Heartbeat

Permanently delete a heartbeat configuration and remove its scheduled job.

DELETE /v1/bot/heartbeat/delete?project_id=proj_abc123&bot_id=bot_xyz789&heartbeat_id=hb_abc123

Get Execution Logs

Retrieve the execution history for a bot’s heartbeats.

GET /v1/bot/heartbeat/logs?project_id=proj_abc123&bot_id=bot_xyz789

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`bot_id`	string	Yes	Bot UUID
`heartbeat_id`	string	No	Filter by specific heartbeat UUID
`member_id`	string	No	Filter by subscriber
`status`	string	No	Filter by status: `success`, `error`, `skipped`
`page`	number	No	Page number (default: 1)
`per_page`	number	No	Results per page (default: 20)

Response

{
  "total": 42,
  "logs": [
    {
      "uuid": "log_abc123",
      "type": "heartbeat",
      "status": "success",
      "prompt": "Check for new support tickets...",
      "response": "Found 3 new tickets...",
      "duration_ms": 4523,
      "tokens_used": 1250,
      "credits_charged": 2,
      "created_at": "2026-02-12T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "total_pages": 3
  }
}

Get Execution Stats

Get aggregated statistics for a bot’s heartbeat executions.

GET /v1/bot/heartbeat/stats?project_id=proj_abc123&bot_id=bot_xyz789&days=30

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`bot_id`	string	Yes	Bot UUID
`days`	number	No	Number of days to aggregate (default: 30)

Response

{
  "stats": {
    "total_executions": 420,
    "success_count": 400,
    "error_count": 15,
    "skipped_count": 5,
    "success_rate": 95.2,
    "total_tokens": 125000,
    "total_credits": 840,
    "avg_duration_ms": 4200,
    "active_heartbeats": 3,
    "by_type": {
      "heartbeat": { "count": 380, "success_rate": 96.1 },
      "scheduled_task": { "count": 40, "success_rate": 90.0 }
    },
    "time_series": [
      { "date": "2026-02-12", "total": 14, "success": 13, "error": 1 },
      { "date": "2026-02-11", "total": 14, "success": 14, "error": 0 }
    ]
  }
}

Error Codes

Code	Description
400	Invalid parameters (e.g., interval below plan minimum)
403	Heartbeat not enabled for this bot, or plan doesn’t support heartbeat
404	Heartbeat not found

Getting Started

Choose Your Path

Providers & Models

Overview

Configure a Heartbeat

Parameters

Example

Response

List Heartbeats

Parameters

Response

Get a Heartbeat

Enable a Heartbeat

Disable a Heartbeat

Trigger a Heartbeat

Response

Delete a Heartbeat

Get Execution Logs

Parameters

Response

Get Execution Stats

Parameters

Response

Error Codes

Next Steps

Bot Management

Heartbeat for Creators

​Overview

​Configure a Heartbeat

​Parameters

​Example

​Response

​List Heartbeats

​Parameters

​Response

​Get a Heartbeat

​Enable a Heartbeat

​Disable a Heartbeat

​Trigger a Heartbeat

​Response

​Delete a Heartbeat

​Get Execution Logs

​Parameters

​Response

​Get Execution Stats

​Parameters

​Response

​Error Codes

​Next Steps

Bot Management

Heartbeat for Creators

Overview

Configure a Heartbeat

Parameters

Example

Response

List Heartbeats

Parameters

Response

Get a Heartbeat

Enable a Heartbeat

Disable a Heartbeat

Trigger a Heartbeat

Response

Delete a Heartbeat

Get Execution Logs

Parameters

Response

Get Execution Stats

Parameters

Response

Error Codes

Next Steps