---
title: Debug view
description: Watch a live, parsed snapshot of every incoming event for 30 minutes, without waiting for it to land in the catalog or analytics.
---

Debug view is a time-boxed capture stream: switch it on for a project and every event
reported in the next 30 minutes is captured into a live feed you can inspect immediately
— useful for confirming an integration is sending exactly what you expect, before
waiting for it to show up anywhere else.

## Prerequisites

- Nothing sent yet is required, but you'll want a way to trigger a test event (your app,
  or a manual `curl` against [Sending events](/docs/sending-data/events)) once the
  switch is on.

## Authentication

The switch and capture-stream endpoints below are **Management API** calls — host
`https://retidal.com`, authenticated with the `trackly_session` cookie from a
logged-in console user, not a project API key. Sending the test event itself in
step 2 below is the one **Ingestion API** call on this page — host
`https://api.retidal.com`, authenticated with `X-API-Key`. See
[Authentication](/docs/authentication) for the full two-API split.

## Switch status

```
GET https://retidal.com/api/projects/{projectId}/debug-mode
```

Returns whether debug mode is currently on for the project and its remaining TTL.
`GET /api/projects/{projectId}/debug-mode` returns `404` for a project you have no
membership in (anti-enumeration — this route never distinguishes a wrong project ID
from one that exists but you can't see).

## Enabling, disabling, renewing

```
POST https://retidal.com/api/projects/{projectId}/debug-mode
```

<ParamField name="action" in="body" type="string" required>
  `enable`, `disable`, or `renew`.
</ParamField>

`POST /api/projects/{projectId}/debug-mode` returns `409` if you try to `renew` while
debug mode isn't currently enabled.

<Note>
  The switch can take up to a minute to take effect (KV cross-node propagation delay).
  For instant debugging on a single event, add a `_debug: 1` field directly to that
  event's payload instead of waiting on the project-level switch — that channel takes
  effect immediately.
</Note>

## The capture stream

```
GET https://retidal.com/api/projects/{projectId}/debug-events
```

An incremental, keyset-paginated stream of captured events (`after` cursor from the
previous response's `nextCursor`, `limit` up to 100). Console → Projects → Debug shows
this same stream live, with the switch toggle above it.

<Warning title="Debug data is retained for 24 hours only">
  Do not rely on the debug stream as persistent storage or as a substitute for the
  [event catalog](/docs/sending-data/event-catalog) — it exists to inspect what just
  happened, not to hold a durable record.
</Warning>

## Confirming one event landed

Console → Projects → Events (the raw event log) is a separate page from this one and
from the event catalog — it is where you look up one specific event row by date range or
property filter after the fact, once you already know roughly what you're looking for.
Debug view is for watching events arrive in real time as they're captured; the raw event
log is for querying what already arrived.

## What this unlocks

Debug view is the fastest confirmation loop while integrating: instead of sending an
event and waiting for it to surface in the [event catalog](/docs/sending-data/event-catalog)'s
volume trend or the raw event log, you see the parsed event body within seconds of
sending it.

## Verify it worked

<Steps>
  <Step title="Enable debug mode">
    Console → Projects → Debug, or, from a browser session already logged into the
    console (so the `trackly_session` cookie is sent automatically):
    ```bash
    curl -s -X POST https://retidal.com/api/projects/{projectId}/debug-mode \
      -H "Cookie: trackly_session=$SESSION_COOKIE" -H "Content-Type: application/json" \
      -d '{"action":"enable"}'
    # expect: 200
    ```
  </Step>
  <Step title="Send a test event tagged for instant capture">
    ```bash
    curl -s -X POST https://api.retidal.com/api/v1/t \
      -H "X-API-Key: $RETIDAL_API_KEY" -H "Content-Type: application/json" \
      -d '{"eventName":"debug_smoke_test","visitorId":"vid_test","_debug":1}'
    # expect: 202 { "accepted": 1, ... }
    ```
  </Step>
  <Step title="Confirm it landed in the capture stream">
    ```bash
    curl -s "https://retidal.com/api/projects/{projectId}/debug-events?limit=1" \
      -H "Cookie: trackly_session=$SESSION_COOKIE"
    # expect: 200 with that event's parsed body visible, within seconds
    ```
    Console → Projects → Debug shows the same stream live.
  </Step>
</Steps>

## If it doesn't work

If this page itself shows nothing for an event you know you sent, that is the same
"why don't my events show up" symptom the tool exists to diagnose — work through
[Events not arriving](/docs/troubleshooting/events-not-arriving).

## Next steps

<CardGroup cols={2}>
  <Card title="Event catalog" href="/docs/sending-data/event-catalog">
    The durable, aggregate view once you're past live debugging.
  </Card>
  <Card title="Sending events" href="/docs/sending-data/events">
    The endpoint every event captured here came through.
  </Card>
</CardGroup>