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

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

Documentation Index

​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