paperclip_list_heartbeat_runs
List heartbeat runs for your company to audit agent execution or diagnose heartbeat failures. Optionally filter by agent.
Instructions
⚠ Board-only: List heartbeat runs for the company, optionally filtered by agent.
Args:
companyId: string — Company UUID (example: "53caad5d-05d6-469d-b6eb-8961a71b615e")
agentId: string (optional) — Filter runs to a specific agent UUID (example: "agt_abc123")
limit: number (optional) — Max runs per page, 1–100 (default 50)
offset: number (optional) — Number of runs to skip (default 0)
response_format: 'markdown' | 'json' (optional) — Output format (default: markdown)
Returns: Pagination envelope { items: HeartbeatRun[], total, count, offset, limit, has_more, next_offset }. Each item: id, agentId, status, startedAt, finishedAt.
Examples:
Use when: auditing recent agent execution runs or diagnosing agent heartbeat failures
Don't use when: you need the raw event stream for a specific run — use paperclip_list_run_events instead
Error Handling:
401: authentication failed → check PAPERCLIP_API_KEY
403: permission denied → board-only endpoint, requires board API key
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | Company UUID | |
| agentId | No | Filter by agent UUID (optional) — omit to list runs across all agents | |
| limit | Yes | Max runs per page (1–100, default 50) | |
| offset | Yes | Number of runs to skip (default 0) | |
| response_format | Yes | Output format: 'markdown' (default, human-readable) or 'json' (structured) | markdown |