Heartbeat & Uptime

The heartbeat system sends periodic pings to the Cordia API to monitor your bot's uptime. By default, it sends a heartbeat every 30 seconds. The server uses these pings to calculate your bot's uptime percentage.

How It Works

When you create a CordiaClient, the heartbeat automatically starts (unless autoHeartbeat: false)
Every 30 seconds (configurable), the SDK sends a POST /heartbeat request
The Cordia backend tracks these pings and calculates uptime based on consecutive successful pings vs missed ones
If your bot goes offline (no pings for >1 minute), it's marked as down

ℹ️Fire and Forget

Heartbeat requests are sent using "fire and forget" — they never throw errors or crash your bot, even if the API is unreachable.

Auto Heartbeat (Default)

By default, the heartbeat starts automatically when you create the client:

JavaScript / TypeScript

Auto heartbeat

typescript

const cordia = new CordiaClient({
  apiKey: 'your-key',
  botId: 'your-bot',
  // autoHeartbeat defaults to true
  // heartbeatInterval defaults to 30000 (30 seconds)
});

// Heartbeat is already running! ❤️
console.log(cordia.isHeartbeatRunning); // true

Python

Auto heartbeat

python

cordia_client = cordia.CordiaClient(
    api_key="your-key",
    bot_id="your-bot",
    # auto_heartbeat defaults to True
)

# Start the background tasks (heartbeat + queue flush)
cordia_client.start(bot.loop)

# Heartbeat is now running! ❤️

Manual Control

JavaScript / TypeScript

Manual heartbeat control

typescript

const cordia = new CordiaClient({
  apiKey: 'your-key',
  botId: 'your-bot',
  autoHeartbeat: false, // Don't start automatically
});

// Start manually when ready
cordia.startHeartbeat();

// Check status
console.log(cordia.isHeartbeatRunning); // true

// Stop when needed
cordia.stopHeartbeat();

Python

Manual heartbeat control

python

cordia_client = cordia.CordiaClient(
    api_key="your-key",
    bot_id="your-bot",
    auto_heartbeat=False,  # Don't start automatically
)

# Start background tasks (specifically the flush loop)
cordia_client.start(bot.loop)

# Start heartbeat manually when ready
cordia_client.start_heartbeat(bot.loop)

# Check status
print(cordia_client.is_heartbeat_running) # True

# Stop when needed
cordia_client.stop_heartbeat()

Custom Interval

JavaScript / TypeScript

Custom heartbeat interval

typescript

const cordia = new CordiaClient({
  apiKey: 'your-key',
  botId: 'your-bot',
  heartbeatInterval: 60000, // Every 60 seconds
});

Python

Custom heartbeat interval

python

cordia_client = cordia.CordiaClient(
    api_key="your-key",
    bot_id="your-bot",
    heartbeat_interval=60000,  # Every 60 seconds (in ms)
)

⚠️Minimum Interval

The minimum heartbeat interval is 5 seconds (5000ms). Values below this will throw an error at initialization.

Uptime Tracking

You can check your bot's uptime programmatically:

JavaScript / TypeScript

Check uptime

typescript

// Get uptime in milliseconds
const uptimeMs = cordia.getUptime();
const uptimeHours = uptimeMs / 1000 / 60 / 60;

console.log(`Bot uptime: ${uptimeHours.toFixed(2)} hours`);

Python

Check uptime

python

# Get uptime in milliseconds
uptime_ms = cordia_client.get_uptime()
uptime_hours = uptime_ms / 1000 / 60 / 60

print(f"Bot uptime: {uptime_hours:.2f} hours")

Heartbeat Payload

Each heartbeat sends the following data:

POST /api/v1/heartbeat

json

{
  "botId": "your-bot-id",
  "timestamp": "2026-04-06T12:00:00.000Z",
  "uptime": 3600000
}

Field	Type	Description
`botId`	`string`	Your bot ID (added automatically)
`timestamp`	`string`	ISO 8601 timestamp of the heartbeat
`uptime`	`number`	Bot uptime in milliseconds since client creation

Graceful Shutdown

Always clean up when shutting down your bot:

JavaScript / TypeScript

Graceful shutdown

typescript

process.on('SIGINT', async () => {
  console.log('Shutting down...');

  // Stops heartbeat + flushes remaining events
  await cordia.destroy();

  client.destroy();
  process.exit(0);
});

Python

Graceful shutdown

python

async def main():
    async with bot:
        try:
            await bot.start(token)
        finally:
            # Stops heartbeat + flushes remaining events
            await cordia_client.close()

💡Process Unref (JS)

The JS heartbeat timer uses unref(), which means it won't prevent your Node.js process from exiting naturally. In Python, the background tasks are cancelled automatically when you call close().

Guild Count

REST API