Pool, Results and Pages
Suggestions waiting on a decision, the results that say what the work changed, and the page registry underneath both.
How the three fit together
Every recommendation Trakkr makes lands in one pool. A person or an agent decides what to do with each one, and committing freezes how that change will be measured. When the window closes, the pipeline measures it and writes a result. Pages are what all of it hangs on: one row per URL, keyed the same way everywhere.
/get-opportunity-pool is not the same thing as /get-opportunities. The older endpoint lists citation outreach targets and keeps working exactly as it does today. This one is the unified pool that every recommendation system writes to.Pool
Suggestions waiting on a decision. The order is deterministic: impact bands first, then each family's freshest items in turn, so one high-volume source cannot crowd out everything else. Nothing here is committed work yet.
Only two statuses ever come back: new and seen. Anything committed, dismissed, snoozed or expired has left the pool, so there is no filter that brings those rows back here.
Query Parameters
brand_idstringrequiredThe brand to read.
familystringfix, refresh, create, earn, discuss, optimize, setup or play.
kindstringComma-separated kinds, e.g. 'search_gap,audit_fix'.
impactstringlow, medium or high.
limitint1-200.
Default: 50
cursorstringOpaque cursor from meta.next_cursor.
Commit, dismiss or snooze
One explicit verb per call. Committing creates tracked work and freezes its measurement plan, which is what makes a before/after result possible later. Dismissing takes a reason. Snoozing hides a suggestion and brings it back.
Parameters
brand_idstringrequiredQuery parameter. The brand that owns the suggestion.
opportunity_idstringrequiredBody. The suggestion to decide on.
actionstringBody. commit, dismiss or snooze.
Default: 'commit'
reasonstringBody. Why it was dismissed. Recommended for action='dismiss'.
snooze_daysintBody. 1-90.
Default: 7
A commit returns status, opportunity_id, action_id and the frozen measurement_plan. Dismiss and snooze return only status and opportunity_id. Setup work is never measured, so its plan comes back null, and committing something already committed returns already_accepted with the existing action id.
snooze_days is validated, not just documented: anything outside 1-90 is rejected with 422 before the call runs. An action other than commit, dismiss or snooze returns 400, and an opportunity_id that belongs to another brand returns 404.Results
What completed work actually changed. Every row is computed by Trakkr's pipeline from real before/after data over the window that was frozen at commit time. Nothing here is self-reported.
A result never claims causation. It says a metric moved during the window, which is a different and more honest statement. Four verdicts are possible: earned (the metric cleared the bar the plan set), no_change (it held steady), harm (it fell, reported as "coincided with a drop"), and couldnt_measure (the data needed was not there, and the reason says which).
Query Parameters
brand_idstringrequiredThe brand to read.
verdictstringearned, no_change, harm or couldnt_measure.
familystringNarrow to one verb family.
daysintOnly results measured in the last 1-3650 days.
limitint1-200.
Default: 50
cursorstringOpaque cursor from meta.next_cursor.
/get-proof remains available as a deprecated compatibility alias for existing integrations.Pages
One row per URL the brand owns or appears on. Because everything is keyed on one canonical URL form, a page here is the same page across crawler data, citations, audits and search. Rows carry the page's bottleneck, meaning the first stage of its funnel that is stuck.
Rows come back newest last_seen_at first. Each one carries id, url, slug, ownership, title, tracked, bottleneck, verdict and last_seen_at. The bottleneck is a funnel stage name (available, reached, understood, relevant, selected or visited) and the verdict is the plain sentence that goes with it. Both are null until there is enough data to name one.
Query Parameters
brand_idstringrequiredThe brand to read.
ownershipstringowned, competitor, editorial, social, video or other.
trackedboolTrue for pages someone chose to watch.
limitint1-200.
Default: 50
cursorstringOpaque cursor from meta.next_cursor.
Pagination
These endpoints use cursors, not offsets. Read meta.next_cursor and pass it back as cursor to get the next page. A null cursor means you have reached the end. Older endpoints such as /get-actions keep their existing offset pagination unchanged.