Click Store Lookup — Support Agent Guide

A walkthrough for the Click Store Lookup screen (Sys Admin only). This is the forensic tool you reach for when a customer says "clicks are missing from my reports" and you need to find out what actually happened.

What this screen is for

Every click we receive is written to a durable store the moment it arrives — before any reporting or aggregation. This screen searches that raw store directly, so you can answer one question with confidence:

Did we actually receive click X — and if so, what did we do with it?

There are three possible answers, and this screen lets you tell them apart:

Captured — we received the click and stored it normally.
Blocked — we received the click but deliberately dropped it (the affiliate was disabled, or their click quota was exhausted).
Never received — we have no record of it at all.

This is for forensic comparison only. The raw store can legitimately differ from what shows in reporting, so don't use it as a reporting data source — use it to explain a discrepancy, not to replace a report.

Who can use it

System Admins / internal support staff only. Affiliates never see this screen.

The two ways to search

There are two lookup modes. Pick whichever the situation gives you.

1. Click ID lookup (fast and precise — prefer this)

If the customer can give you a specific Click ID, use it. It's the fastest, most exact path: enter the affiliate, paste the Click ID, search.

When you provide a Click ID, the date range is ignored — the lookup goes straight for that one click.

2. Date range scan (when you don't have a Click ID)

When there's no specific ID, search by:

an affiliate (always required), plus
a date range (maximum 31 days), and
optionally a dynamic parameter to narrow the results to clicks carrying that value.

This scans many small files across the chosen days, so a wide range — especially with a dynamic-parameter filter — can take a few seconds. Narrow the range when you can.

The fields

Field	Required?	Notes
Affiliate	Always	Pick the affiliate the customer is asking about.
Click ID	Optional	A specific click's ID. When set, the date range is ignored.
From / To date	Required unless a Click ID is set	UTC, inclusive by day. Span must be 31 days or less.
Dynamic parameter	Optional	Case-insensitive match on the click's dynamic parameter (sub id / d-param).
Include blocked	Optional, on by default	Also searches blocked clicks. Leave it on for "missing click" cases — a blocked click is often the answer.

The happy path

Pick the affiliate. This is always required.
Choose your mode:
- Have a Click ID? Paste it in. (You can skip the dates.)
- No Click ID? Set a From and To date — keep the span ≤ 31 days — and optionally add a dynamic parameter to narrow it.
Leave "Include blocked" on so a deliberately-blocked click shows up rather than looking like it vanished.
Search. A date-range scan may take a few seconds — wait for the loading state to finish.
Read the results (next section).

Reading the results

You get a table where each row is one full captured click record, exactly as we stored it. The fields vary from click to click — common ones are the Click ID, date, dynamic parameter, destination URL, and the query string — and there's a raw / JSON view for everything else on a row.

Two summary numbers come back with the results:

Count — how many clicks matched.
Execution time — how long the search took on the server. Useful to mention when a scan was slow ("that took 4 seconds because the range was wide").

The source badge — captured vs. blocked

Every row shows its source, and this is the most important thing to read:

Source	What it means
`clicks/…`	Captured normally — we received and kept this click.
`blocked-clicks/…`	Blocked on purpose — we received it but dropped it because the affiliate was disabled or their click quota was exhausted.

A click in blocked-clicks/ is not a bug and not a lost click — it's a click we deliberately chose not to count. That distinction is usually the answer to the customer's question.

An empty result is a real answer

No rows / count = 0 is a valid outcome, not an error. It means we have no record of that click in the raw store — i.e. it never reached us. Read it as "not found," and treat it as a legitimate finding, not a failure.

Interpreting the outcome

Once you've searched, map the result to one of three answers:

What you see	What to tell the customer
Row(s) under `clicks/…`	We captured the click(s) normally. If reporting still doesn't show them, the gap is downstream of capture — escalate.
Row(s) under `blocked-clicks/…`	We received the click but blocked it on purpose (affiliate disabled, or click quota exhausted). It won't appear in reports by design.
Empty (count = 0)	We never received this click. The problem is upstream of us — the customer's link, tracking, or traffic source.

Common questions

"The customer swears they sent a click but I get no results"

An empty result means it never reached the store. Double-check:

The affiliate is correct.
The date range actually covers when the click happened (remember dates are UTC, inclusive by day — a click late in the customer's local day may fall on the next UTC day).
If you searched by a dynamic parameter, try without it — the value may not match exactly (the match is case-insensitive but still has to be the same value).

If it's still empty after that, the click genuinely never arrived → upstream issue, not ours.

"I found the click but it's under `blocked-clicks/`"

That click was received and deliberately dropped. The usual reasons are the affiliate being disabled at the time, or their click quota being exhausted. It's working as intended — explain why it isn't in their reports.

"The search is taking forever"

Wide date ranges with a dynamic-parameter filter scan a lot of small files. Either narrow the date range, or — if the customer can give you one — switch to a Click ID lookup, which is near-instant.

"I found the click in `clicks/` but it's still not in their report"

Capture is fine, so the discrepancy is somewhere after capture (transform, aggregation, mapping). This is the one case to escalate — the raw store has done its job.

Things to know

Click ID beats everything. If you have one, use it — it's instant and exact, and the date range is ignored.
Keep "Include blocked" on for missing-click investigations. A blocked click is frequently the whole explanation.
Dates are UTC and inclusive by day. Mind the timezone gap when a customer quotes a local time near midnight.
Max 31-day span. A wider range is rejected — split it into chunks if needed.
Empty ≠ broken. Count = 0 is the "never received" answer.
The page remembers your search in the URL. Your affiliate, Click ID, date range, and filters are kept in the address bar — so you can reload without losing them, and you can copy the link to a teammate to reproduce the exact same search.
This is the raw store, not reporting. It can differ from reports by design; use it to explain a difference, not as a reporting source.

Recovering missing clicks

Sometimes the lookup confirms the clicks are in storage (under clicks/…) but they're still missing from reports — typically after an ingest hiccup. When that happens you can replay those stored clicks back into the database, right from this screen, with the Recover clicks button.

When to use it

Use Recover only after you've confirmed, with a search above, that clicks exist in storage for the affiliate and window but aren't showing in reports. It's the fix for "we captured them but they never landed in the database."

How it works

Pick the affiliate and the date range you want to replay (the same ones you just searched). Recovery always works on a date range — if you have a Click ID in the box, clear it first; the button stays disabled until you do.
Leave Include blocked as you want it — with it on, blocked clicks are replayed too (they return to the blocked store, not the database, since they were blocked for a reason).
Click Recover clicks and confirm.
You'll see a message like "Queued 1,240 clicks for recovery." Re-check the affiliate's reports a little later — the recovered clicks appear once the ingest pipeline processes them.

What to keep in mind

It's asynchronous. The count is how many clicks were queued for re-ingest, not how many are already in the database. "Queued 1,240" means they're on their way, not that they're there yet — give the pipeline a little time.
It's safe to re-run. Re-ingesting a click that already exists is ignored, so running it again won't create duplicates. If you're unsure whether it took, just run it again.
One affiliate at a time. There's no all-affiliates option — recover each affiliate's window separately.
A count of 0 is meaningful. It means nothing was captured to storage for that affiliate/window, or those clicks were never stored in the first place (some traffic goes straight to the queue and isn't in the raw store, so it can't be recovered this way). It's not an error.

When to escalate to engineering

A click is present under clicks/… (captured normally) but still doesn't appear in the affiliate's reports → the gap is downstream of capture.
The search returns an error (not an empty result — an actual error message).
Results look internally inconsistent, or a click you can independently confirm arrived shows neither under clicks/ nor blocked-clicks/.