GET /api/v1/overview

Purpose

GET /api/v1/overview returns the top-level counters for the campaign operations page:

• campaigns_total
• players_targeted_total
• players_activated_total
• sent_notifications_total
• support_cases_total

Query parameters

Query param	Meaning	How it is used
tenant_id	Optional tenant scope	Applied to CRM, Lumio, and trigger-side attribution where tenant data exists
from	Optional lower time bound	Applied to reward activity, CRM actions, Spark Bonus dispatches, and Lumio conversation created_at
to	Optional upper time bound	Applied to the same activity windows

Invalid from and to values are ignored by the handler.

Data sources

The endpoint builds a combined campaign record set, then derives counters from that set plus Lumio chat conversations.

Counter	How it is filled	Primary source(s)
campaigns_total	Number of campaign records considered relevant to the requested window	CRM lifecycle_pools, content_pools, bonuses, content; Notify Triggers flows_v2, flow_versions_v2, flow_runs_v2, flow_working_copies_v2, flow_release_attempts_v2; Spark Bonus dispatches
players_targeted_total	Unique count of TargetedKeys across the merged campaign records	CRM actions_log; Notify Triggers flow_runs_v2; Spark Bonus dispatches
players_activated_total	Unique count of ActivatedKeys across the merged campaign records	CRM reward_log; Spark Bonus dispatches
sent_notifications_total	Sum of per-campaign notification counts	CRM actions_log; Notify Triggers flow_runs_v2 successful notify.send_* actions
support_cases_total	Count of Lumio chat conversations only	Lumio conversations with channel = "chat"

How the repository builds it

1. Load CRM campaign records

CRM campaign records are seeded from CRM.lifecycle_pools stage references, joined to:

• CRM.content_pools
• CRM.bonuses
• CRM.content
• CRM.reward_log
• CRM.actions_log

Those reads produce campaign rows with:

• campaign identity and title
• inferred type, benefit, scope, status
• targeted-player keys from actions_log
• activated-player keys from reward_log
• notification counts from actions_log

2. Load trigger-backed reactive campaign records

Reactive campaign rows are built from Notify Triggers flows that contain at least one notify.send_* action in a flow version. The repository joins:

• notify_triggers.flows_v2
• notify_triggers.flow_versions_v2
• notify_triggers.flow_runs_v2
• notify_triggers.flow_working_copies_v2
• notify_triggers.flow_release_attempts_v2
• spark_bonus.dispatches

Those reads produce campaign rows with:

• flow identity and flow name
• inferred type, benefit, scope, status
• notification counts from successful notification action nodes in flow runs
• targeted and activated attribution partly from Spark Bonus dispatches

3. Apply the requested time window

The overview path first loads activity-filtered campaign records, then keeps only records relevant to the requested window.

A campaign is considered relevant when any of the following is true:

• it has targeted players
• it has activated players
• it has sent notifications
• its campaign window overlaps the requested from and to

4. Count support cases

support_cases_total is counted separately from Lumio using:

• database: Lumio
• collection: conversations
• filter: channel = "chat"
• optional tenant filter: tenant_id
• optional time filter: created_at

Relay email and SMS threads are excluded.

Field-by-field meaning

Field	Meaning in this endpoint	Important detail
campaigns_total	Count of CRM and trigger campaign records relevant to the window	This is a campaign-record count, not a count of unique bonuses or flow runs
players_targeted_total	Unique size of the merged TargetedKeys set	CRM uses real player IDs; trigger flows currently mix synthetic run keys and Spark Bonus player keys
players_activated_total	Unique size of the merged ActivatedKeys set	Trigger-side activation comes from successful Spark Bonus dispatches
sent_notifications_total	Sum of sent-notification counters across campaigns	Trigger-side counts reflect successful notification action executions, not provider delivery receipts
support_cases_total	Lumio chatbot conversation count	No campaign-level attribution is attempted here

Truth gaps to keep in mind

• The field name players_targeted_total is most truthful for CRM-backed campaigns. For trigger-backed campaigns, the current implementation can mix synthetic run:<flow_run_id> keys with real player:<player_id> keys, so it is not a pure unique-player count.
• support_cases_total is truthful only as a top-level Lumio chat total. It does not mean "support cases caused by these campaigns".
• Trigger-side notification counts come from executed notify.send_* action nodes, not from downstream delivery confirmations.