Heartbeat Run Records

Schema of heartbeat_runs: id, agent_id, company_id, started_at, completed_at, status, tokens_used, cost_usd, output_summary, error_message. How to query and interpret each field.

Reading and Querying Heartbeat Runs

What you'll learn

The complete heartbeat_runs schema, useful queries for monitoring performance and cost over time, and how to correlate runs with specific issues and agents.

The heartbeat_runs Table

CREATE TABLE public.heartbeat_runs (
  id               uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
  company_id       uuid        NOT NULL REFERENCES companies(id),
  status           text        NOT NULL DEFAULT 'running'
                               CHECK (status IN ('running','completed','failed','skipped')),
  agents_invoked   int         NOT NULL DEFAULT 0,
  issues_claimed   int         NOT NULL DEFAULT 0,
  issues_resolved  int         NOT NULL DEFAULT 0,
  issues_failed    int         NOT NULL DEFAULT 0,
  total_cost_usd   numeric(10,4) NOT NULL DEFAULT 0,
  error_detail     jsonb,      -- array of error objects if status='failed'
  skip_reason      text,       -- 'company_paused', 'no_open_issues', etc.
  started_at       timestamptz NOT NULL DEFAULT now(),
  finished_at      timestamptz
);

Key Queries

Last 7 Days of Run History

SELECT
  DATE(started_at)                         AS date,
  COUNT(*)                                 AS total_runs,
  SUM(issues_resolved)                     AS issues_done,
  SUM(total_cost_usd)                      AS daily_cost,
  AVG(EXTRACT(epoch FROM (finished_at - started_at)))::int AS avg_seconds
FROM heartbeat_runs
WHERE company_id = 'your-company-id'
  AND started_at >= now() - interval '7 days'
GROUP BY DATE(started_at)
ORDER BY date DESC;

Failed Runs with Error Detail

SELECT
  id,
  started_at,
  error_detail,
  skip_reason
FROM heartbeat_runs
WHERE company_id = 'your-company-id'
  AND status IN ('failed', 'skipped')
ORDER BY started_at DESC
LIMIT 20;

Cost Trend Over Time

SELECT
  date_trunc('hour', started_at) AS hour,
  SUM(total_cost_usd)            AS cost_per_hour,
  SUM(issues_resolved)           AS issues_per_hour
FROM heartbeat_runs
WHERE company_id = 'your-company-id'
  AND started_at >= now() - interval '24 hours'
GROUP BY hour
ORDER BY hour;

Runs That Resolved at Least One Issue

SELECT
  id,
  agents_invoked,
  issues_resolved,
  total_cost_usd,
  EXTRACT(epoch FROM (finished_at - started_at))::int AS seconds
FROM heartbeat_runs
WHERE company_id = 'your-company-id'
  AND issues_resolved > 0
ORDER BY started_at DESC
LIMIT 10;

Monthly Summary

SELECT
  to_char(date_trunc('month', started_at), 'YYYY-MM') AS month,
  COUNT(*)                 AS total_runs,
  SUM(issues_resolved)     AS issues_resolved,
  SUM(total_cost_usd)      AS total_cost,
  COUNT(*) FILTER (WHERE status = 'failed') AS failed_runs
FROM heartbeat_runs
WHERE company_id = 'your-company-id'
GROUP BY month
ORDER BY month DESC;

Correlating Runs to Issues

-- Which heartbeat run resolved a specific issue?
SELECT hr.id, hr.started_at, hr.total_cost_usd
FROM heartbeat_runs hr
JOIN issues i ON i.heartbeat_run_id = hr.id
WHERE i.id = 'your-issue-id';

Checkpoint ✓

• [ ] You can query the last 7 days of run history with cost per day
• [ ] You can find failed runs and read their error details
• [ ] You know how to correlate a specific issue to the run that resolved it