# list_custom_events

Inspect safe app-scoped custom observations.

## Purpose

Inspect safe app-scoped custom observations.

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

Optional filters are `name` (exact normalized event name), `source` (`api` or `pixel`), `origin` (`app_reported`, `browser_reported`, `unknown`) and exact permanent `shop` domain. API transport does not independently prove server-side evidence: forwarded storefront observations remain browser reported. Origin is a reported claim, not external verification.

## 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": "list_custom_events",
    "arguments": {
      "appId": "11111111-1111-4111-8111-111111111111",
      "from": "2026-09-01T00:00:00Z",
      "to": "2026-10-01T00:00:00Z"
    }
  }
}
```

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 full-window `total`, paginated `items`, occurrence and original receipt times, transport, reported origin and exact merchant identity or an unresolved reason. Properties are returned only when explicitly allowed by a saved definition and accepted by the sensitive key/value filters. Raw payloads and external event IDs are not exposed. Use the dedicated receipt tool when you know the exact external event ID.

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