Deployments.ai Docs
Command reference

deployments heartbeat

Agent liveness and heartbeat events

CommandSummary
deployments heartbeat createCreate a heartbeat
deployments heartbeat listList heartbeats
deployments heartbeat showShow a heartbeat
deployments heartbeat updateUpdate a heartbeat
deployments heartbeat archiveArchive a heartbeat
deployments heartbeat pausePause a heartbeat
deployments heartbeat resumeResume a heartbeat
deployments heartbeat firesList heartbeat fire history
deployments heartbeat fireFire a heartbeat now

deployments heartbeat create

Create a heartbeat.

deployments heartbeat create --agent-deployment-id <agent-deployment-id> --instructions <instructions>
  • Calls POST /v1/heartbeats (SDK createHeartbeat).
  • Needs an environment: --env or the saved context.
  • Sends an idempotency key. The CLI generates one per run; pass --idempotency-key to retry safely.
FlagTypeRequiredDefaultDescription
--active-windowstring (json)Heartbeat active window
--agent-deployment-idstringyesAgent deployment ID
--instructionsstringyesHeartbeat run instructions
--interval-msstring (number)Heartbeat interval in milliseconds
--no-skip-when-busybooleanRun even while the deployment has an active run
--skip-when-busybooleanSkip while the deployment has an active run
--thread-idstringConversation thread for heartbeat runs
--timezonestringIANA timezone
--workspace-idstringWorkspace ID

Also accepts the global flags.

deployments heartbeat list

List heartbeats.

deployments heartbeat list
  • Calls GET /v1/heartbeats (SDK listHeartbeats).
  • Needs an environment: --env or the saved context.
  • Paginated. --page-size sets the page size; pass the returned cursor as --cursor for the next page.
FlagTypeRequiredDefaultDescription
--cursorstring (cursor)Pagination cursor
--page-sizestring (number)Page size

Also accepts the global flags.

deployments heartbeat show

Show a heartbeat.

deployments heartbeat show <id>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID

Also accepts the global flags.

deployments heartbeat update

Update a heartbeat.

deployments heartbeat update <id>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID
--active-windowstring (json)Heartbeat active window
--clear-active-windowbooleanClear the heartbeat active window
--clear-timezonebooleanClear the heartbeat timezone
--instructionsstringHeartbeat run instructions
--interval-msstring (number)Heartbeat interval in milliseconds
--no-skip-when-busybooleanRun even while the deployment has an active run
--skip-when-busybooleanSkip while the deployment has an active run
--timezonestringIANA timezone

Also accepts the global flags.

deployments heartbeat archive

Archive a heartbeat.

deployments heartbeat archive <id>
  • Calls DELETE /v1/heartbeats/{heartbeatId} (SDK archiveHeartbeat).
  • Needs an environment: --env or the saved context.
  • Destructive. Live runs ask for confirmation; pass --yes in scripts or with --json.
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID

Also accepts the global flags.

deployments heartbeat pause

Pause a heartbeat.

deployments heartbeat pause <id>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID

Also accepts the global flags.

deployments heartbeat resume

Resume a heartbeat.

deployments heartbeat resume <id>
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID

Also accepts the global flags.

deployments heartbeat fires

List heartbeat fire history.

deployments heartbeat fires <id>
  • Calls GET /v1/heartbeats/{heartbeatId}/fires (SDK listHeartbeatFires).
  • Needs an environment: --env or the saved context.
  • Paginated. --page-size sets the page size; pass the returned cursor as --cursor for the next page.
FlagTypeRequiredDefaultDescription
--cursorstring (cursor)Pagination cursor
--page-sizestring (number)Page size
<id>positionalyesResource ID

Also accepts the global flags.

deployments heartbeat fire

Fire a heartbeat now.

deployments heartbeat fire <id> --agent-deployment-id <agent-deployment-id>
  • Calls POST /v1/heartbeats/{heartbeatId}/fire (SDK fireHeartbeat).
  • Needs an environment: --env or the saved context.
  • Sends an idempotency key. The CLI generates one per run; pass --idempotency-key to retry safely.
FlagTypeRequiredDefaultDescription
<id>positionalyesResource ID
--agent-deployment-idstringyesAgent deployment ID
--fire-keystringStable fire key

Also accepts the global flags.

On this page