# get_activation_journey

Inspect one exact merchant journey and available facts.

## Purpose

Inspect one exact merchant journey and available facts.

## 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_journey",
    "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,
      "shop": "example.myshopify.com"
    }
  }
}
```

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

Returns the shared `report`, selected `journey` or null, paginated safe `facts`, `totalFacts`, `nextCursor` and paginated `otherEpisodes`, `totalOtherEpisodes` and `nextEpisodeCursor`. Fact kinds distinguish lifecycle, custom and collection observations. Lifecycle facts have no custom receipt time. The timeline contains available facts within the bounded report load; it is not a promise of the merchant’s complete history. A historical completed installation does not establish completion of a later reinstall.

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

## Select and page episodes

Optional `episode` is the exact returned episode key. It must belong to this merchant, app, saved funnel/version and entry cohort. Omitting it retains earliest-cohort selection. Choosing another episode changes the contextual journey, while report totals keep the earliest-episode aggregation. Use `episodeCursor` with the unchanged selection to page other episodes separately from the fact `cursor`. Both lists use `limit` (default 50, maximum 100). Entries outside the cohort can appear as context but cannot be selected without choosing the applicable cohort.

## 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`.