Debug view

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) 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 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

actionbodystringrequired

enable, disable, or renew.

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

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.

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.

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 — it exists to inspect what just happened, not to hold a durable record.

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’s volume trend or the raw event log, you see the parsed event body within seconds of sending it.

Verify it worked

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

2. 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, ... }

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

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.

Next steps

Event catalog

The durable, aggregate view once you’re past live debugging.

Sending events

The endpoint every event captured here came through.