Skip to main content

​
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

ParameterTypeRequiredDescription
project_idstringYesProject UUID
bot_idstringYesBot UUID
promptstringYesThe instruction the agent executes each run
cron_patternstringNoCron expression for scheduling (e.g., 0 9 * * 1 for every Monday at 9am)
enabledbooleanNoWhether the heartbeat is active (default: false)
timezonestringNoTimezone for scheduling (default: UTC)
credit_budgetnumberNoMax credits per billing period (null = unlimited)
max_consecutive_errorsnumberNoAuto-pause after this many consecutive failures (default: 5)
member_idstringNoSubscriber 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

ParameterTypeRequiredDescription
project_idstringYesProject UUID
bot_idstringYesBot UUID
member_idstringNoFilter 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

ParameterTypeRequiredDescription
project_idstringYesProject UUID
bot_idstringYesBot UUID
heartbeat_idstringNoFilter by specific heartbeat UUID
member_idstringNoFilter by subscriber
statusstringNoFilter by status: success, error, skipped
pagenumberNoPage number (default: 1)
per_pagenumberNoResults 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

ParameterTypeRequiredDescription
project_idstringYesProject UUID
bot_idstringYesBot UUID
daysnumberNoNumber 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

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

​
Next Steps

Bot Management

Enable heartbeat on your bot

Heartbeat for Creators

No-code heartbeat setup guide