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

# Heartbeat API

> Create and manage autonomous agent schedules via the 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.

<Info>
  Before using the Heartbeat API, the bot must have heartbeat enabled. Set `heartbeat: true` via the [Bot Management API](/sdk/core/bot-management) update endpoint.
</Info>

## Configure a Heartbeat

Create or update a heartbeat configuration for a bot.

```bash theme={null}
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

```javascript theme={null}
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

```json theme={null}
{
  "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.

```bash theme={null}
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

```json theme={null}
{
  "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.

```bash theme={null}
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.

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

```json theme={null}
{
  "project_id": "proj_abc123",
  "bot_id": "bot_xyz789",
  "heartbeat_id": "hb_abc123"
}
```

## Disable a Heartbeat

Pause a heartbeat without deleting its configuration.

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

```json theme={null}
{
  "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.

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

```json theme={null}
{
  "project_id": "proj_abc123",
  "bot_id": "bot_xyz789",
  "heartbeat_id": "hb_abc123"
}
```

### Response

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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

```json theme={null}
{
  "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.

```bash theme={null}
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

```json theme={null}
{
  "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                                                   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Bot Management" icon="robot" href="/sdk/core/bot-management">
    Enable heartbeat on your bot
  </Card>

  <Card title="Heartbeat for Creators" icon="heart-pulse" href="/creators/heartbeat">
    No-code heartbeat setup guide
  </Card>
</CardGroup>