# get_activation_funnel

Read a complete cohort report or filtered merchant drill.

## Purpose

Read a complete cohort report or filtered merchant drill.

## Access and effects

Owner workspace credential only; member, partner and app-bound affiliate credentials cannot use these tools. Reads do not change definitions, start reconciliation, create events, run automations or send messages. Use the owned app UUID from [list_apps](/docs/mcp/list-apps).

## Scope and pagination

`appId` is required. `from` is inclusive and `to` exclusive, both UTC ISO timestamps ending in Z. Omitted dates select the preceding 30 days through query time; a forward window of at most 365 days is required. Page `limit` defaults to 50 and allows 1–100. Use the returned `nextCursor` unchanged with the same app, window, filters and version. A copied cursor from another scope is rejected. Keep explicit dates and version for repeatable inspection.

`funnelId` is required; `version` defaults to the current owned version. Pin it explicitly when comparing results. The window selects journey entries; matching observations may follow those entries through the saved conversion window. Install/reinstall boundaries constrain the episode. See [Activation](/docs/app-owners/activation) for the report states and denominator rules.

## Example request

These identifiers are fictional. Replace them with your owned app, saved funnel/version and merchant.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_activation_funnel",
    "arguments": {
      "appId": "11111111-1111-4111-8111-111111111111",
      "from": "2026-09-01T00:00:00Z",
      "to": "2026-10-01T00:00:00Z",
      "funnelId": "22222222-2222-4222-8222-222222222222",
      "version": 1
    }
  }
}
```

POST to `https://heycrust.com/api/mcp` with `Content-Type: application/json` and `Authorization: Bearer <YOUR_CREDENTIAL>`. Inspect JSON-RPC errors and `result.isError`, then parse the JSON text in `result.content`.

## Result and interpretation

Without `includeMerchants`, returns the full cohort report, pinned definition/version, generation time, source/declaration coverage and stage denominators. With `includeMerchants: true`, returns `report`, paginated journey `items`, the full filtered `total` and `nextCursor`. Optional `stage` and `state` select a drill; a state requires a stage. Paging does not change report totals. An unavailable report carries reasons and null totals with no partial stage counts.

See [event observability](/docs/developers/event-observability) for definitions, deployment declarations and privacy boundaries.

## Query timeouts

A recognized PostgreSQL timeout returns `status: unavailable` and `reasons: [query_timeout]`, with no fabricated totals. Check status/reasons before interpreting the result; narrow the window or retry. A complete activation report can also be unavailable for fact/journey limits or `calculation_timeout`.