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

# get_program_report

> The whole event program in one call: the dashboard funnel, one row per event, cost per meeting, velocity and coverage.

> [!NOTE]
>
> Read-only.

It answers "how is the event program doing?" in one response, ready for a chart or a summary. It owns no number: each block is another tool's output, named in `sources`. Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "Give me a quarterly summary of our event program."
* "Chart our funnel from MQL to closed won."
* "Which events drove the most pipeline this year?"
* "Make me a slide on event ROI."

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `time_range` | string | No | `last_30_days`, `this_quarter`, `last_quarter`, `ytd` or `program_total` (default). Any other value is `invalid_parameter`. |
| `contract_version` | string | No | Omit for `v1`. |

`time_range` is the only narrowing parameter. It windows the funnel and the event rows the way the dashboard tab does; `program_summary`, `velocity_comparison` and `coverage` are program-wide and never windowed.

## Response

| Field | Meaning |
| - | - |
| `time_range`, `window` | The range asked for and the instants applied. |
| `funnel` | The dashboard's own funnel `steps`, each with `label`, `source`, `field`, `count`, `count_source`, `canonical_stage`, `complete`. Plus `computed_at`, `freshness`, `complete` and `incomplete_reasons`. |
| `events` | [`get_event_attribution`](https://heybtw.com/docs/tools/get-event-attribution)'s per-event rows without the deal breakdown. Upcoming events carry `event_tense` and `registered_account_pipeline`. |
| `program_summary` | `cost_per_meeting`, program-wide, verbatim from `get_event_attribution`. |
| `velocity_comparison` | Event-touched vs. non-touched deals, verbatim from `get_event_attribution`. |
| `coverage` | [`get_data_health`](https://heybtw.com/docs/tools/get-data-health) verbatim. |
| `sources` | The canonical tool behind each block. |

The sample below is trimmed from a real `program_total` call (fixture data; one event row of four shown).

```json theme={null}
{
  "tool": "get_program_report",
  "data": [
    {
      "time_range": "program_total",
      "window": { "date_from": null, "date_to": null, "authority": "bridge" },
      "funnel": {
        "computed_at": "2026-11-03T19:36:48.062Z",
        "freshness": { "age_seconds": 0, "stale": false, "window_seconds": 300 },
        "complete": true,
        "incomplete_reasons": [],
        "steps": [
          { "id": "mqls", "label": "MQLs", "source": "attio_deal_stage", "field": "Lead", "count": 25, "count_source": "per_step", "canonical_stage": "mql", "complete": true },
          { "id": "meetings_booked", "label": "Meetings Booked", "source": "attio_deal_stage", "field": "Meeting Booked", "count": 22, "count_source": "per_step", "canonical_stage": "meeting_booked", "complete": true },
          { "id": "opportunities", "label": "Opportunities", "source": "attio_deal_stage", "field": "Opportunity", "count": 17, "count_source": "per_step", "canonical_stage": "opportunity", "complete": true },
          { "id": "closed_won", "label": "Closed Won", "source": "attio_deal_stage", "count": 5, "count_source": "per_step", "canonical_stage": "closed_won", "complete": true }
        ]
      },
      "events": [
        {
          "event_name": "ScaleUp.ai x Partners: NYC Tech Week Open House",
          "channel_id": "cmvifxuom000o07l2hioks7wf",
          "event_date": "2026-05-05T22:00:00",
          "total_signups": 46,
          "mql_count": null,
          "crm_joined": true,
          "crm_join_key": null,
          "pipeline": { "total_revenue": 536000, "sourced_revenue": 536000, "influenced_revenue": 0, "won_revenue": 140000, "company_count": 6 }
        }
      ],
      "event_count": 4,
      "program_summary": {
        "cost_per_meeting": { "total_invested_usd": 6000, "paid_event_count": 1, "meetings_from_paid_events": 0, "cost_per_meeting_usd": null }
      },
      "velocity_comparison": {
        "event_touched_avg_days_to_close": null,
        "non_touched_avg_days_to_close": null,
        "event_touched_win_rate": 0.167,
        "non_touched_win_rate": 0.214,
        "win_rate_lift_pp": -4.8,
        "event_touched_count": 12,
        "non_touched_count": 14
      },
      "sources": {
        "events": "get_event_attribution per-event rows (rollup fields)",
        "program_summary": "get_event_attribution program_summary, verbatim",
        "coverage": "get_data_health, verbatim"
      }
    }
  ],
  "metadata": { "contract_version": "v1" },
  "status": "partial"
}
```

The `coverage` block is omitted from the sample; it is the [`get_data_health`](https://heybtw.com/docs/tools/get-data-health) row. On this workspace every funnel step is a CRM deal stage, which counts every deal at that stage whatever the window, so the per-event funnel counts are `null`.

## Rules the agent must follow

* Report each number as its source tool would. Never compute a rate, a ratio or a composite from these blocks, and never rank events by a score.
* A step with `complete: false` is a lower bound. Say so, with `funnel.incomplete_reasons`.
* A `stale` funnel reads as of `computed_at`. Say when it was computed.
* Upcoming events show 0 attributed. Their `registered_account_pipeline` is never attribution and never goes into a total.
* A negative lift in `velocity_comparison` is a fact to relay as served, not a verdict on the program.
* Read `crm_context` first. When heyBTW does not read deals, the CRM-derived counts are `null` with one gap; use the user's own CRM connector for those questions.

## Errors and gaps

| Code | What it means | What to do |
| - | - | - |
| `invalid_parameter` | A `time_range` outside the five values. | Pick one of the five. |
| `partial_coverage` (funnel or attribution) | Forwarded verbatim from `get_event_attribution` and `get_data_health`. `retryable: false`. | Relay them. A remedy naming `time_range` applies to the funnel and event rows only. |
| `stale_data` | The funnel is older than 300 seconds. `retryable: true`. | Report it as of `computed_at`, or retry. |
| `scope_truncated` | More than 500 events in the window. | Use a narrower `time_range`. |
| `internal_error` | Failure on heyBTW's side. | Retry once. |

## Related

* [`get_event_attribution`](https://heybtw.com/docs/tools/get-event-attribution): the deal breakdown behind each row.
* [`get_data_health`](https://heybtw.com/docs/tools/get-data-health): the coverage block on its own.
* [`get_workspace_overview`](https://heybtw.com/docs/tools/get-workspace-overview): the funnel totals with integration status.
* Playbook: [Did anyone follow up, and what did the event do for pipeline](https://heybtw.com/docs/playbooks/follow-up-and-roi.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.