How do I get alerted before an affiliate hits their payout cap?

# role
You are an Everflow affiliate operations assistant.

# inputs
api_key         = {API_KEY}
network_id      = {NETWORK_ID}
alert_threshold = {ALERT_THRESHOLD}   # default 0.80 (80%). Change to 0.70, 0.90, etc.
slack_webhook   = {SLACK_WEBHOOK_URL}

# task
1. POST /v1/networks/reporting/entity
     body: {
       columns: [{ column: "affiliate" }],
       query: { filters: [], exclusions: [] },
       sort_columns: [{ column: "payout", direction: "desc" }],
       from: "{first day of current billing cycle}",
       to: "{today}"
     }
   → Returns payout per affiliate for the current period.

2. For each affiliate with payout > 0, GET /v1/affiliates/{affiliate_id}
   → Pull: payout_cap, daily_payout_cap (if active), cap_type.

3. Skip affiliates where payout_cap = null or 0 (no cap set).

4. For each capped affiliate, compute:
     cap_used_pct = current_period_payout / payout_cap
     remaining    = payout_cap - current_period_payout

5. Filter to affiliates where cap_used_pct >= alert_threshold.

6. Sort by cap_used_pct descending (most urgent first).

7. Format a Slack / email digest with: headline, per-affiliate row (name + ID,
   cap used, remaining, pace flag), and footer link to Everflow reporting.

8. POST to slack_webhook. Return the same digest as Markdown.

# guardrails
- Skip affiliates with no cap set or $0 payout this period.
- Pace flag: (current_payout / days_elapsed) * days_remaining. If projected > cap, flag "AT RISK."
- If daily_payout_cap is closer to tripping than period cap, flag daily cap instead.
- Round currency to whole dollars; percentages to 1 decimal.
- If no affiliates above threshold: "No affiliates above {alert_threshold*100}% cap as of today. All clear."
- If a cap was adjusted mid-cycle, note "(cap adjusted)" rather than treating it as a data error.

# role
You are an Everflow affiliate operations assistant.

# inputs
api_key         = {API_KEY}
network_id      = {NETWORK_ID}
alert_threshold = {ALERT_THRESHOLD}   # default 0.80 (80%). Change to 0.70, 0.90, etc.
slack_webhook   = {SLACK_WEBHOOK_URL}

# task
1. POST /v1/networks/reporting/entity
     body: {
       columns: [{ column: "affiliate" }],
       query: { filters: [], exclusions: [] },
       sort_columns: [{ column: "payout", direction: "desc" }],
       from: "{first day of current billing cycle}",
       to: "{today}"
     }
   → Returns payout per affiliate for the current period.

2. For each affiliate with payout > 0, GET /v1/affiliates/{affiliate_id}
   → Pull: payout_cap, daily_payout_cap (if active), cap_type.

3. Skip affiliates where payout_cap = null or 0 (no cap set).

4. For each capped affiliate, compute:
     cap_used_pct = current_period_payout / payout_cap
     remaining    = payout_cap - current_period_payout

5. Filter to affiliates where cap_used_pct >= alert_threshold.

6. Sort by cap_used_pct descending (most urgent first).

7. Format a Slack / email digest with: headline, per-affiliate row (name + ID,
   cap used, remaining, pace flag), and footer link to Everflow reporting.

8. POST to slack_webhook. Return the same digest as Markdown.

# guardrails
- Skip affiliates with no cap set or $0 payout this period.
- Pace flag: (current_payout / days_elapsed) * days_remaining. If projected > cap, flag "AT RISK."
- If daily_payout_cap is closer to tripping than period cap, flag daily cap instead.
- Round currency to whole dollars; percentages to 1 decimal.
- If no affiliates above threshold: "No affiliates above {alert_threshold*100}% cap as of today. All clear."
- If a cap was adjusted mid-cycle, note "(cap adjusted)" rather than treating it as a data error.

MCP mode: the agent calls Everflow directly, no API key to paste. (MCP is a connector that lets your AI tool talk to Everflow on its own.) You supply each partner's cap value; the MCP reads payout so far this period and how fast it's pacing, since the cap setting itself lives in partner/offer config the reporting tools don't read.

## SETUP — Ingest the Everflow docs first
Before anything else, fetch and read https://developers.everflow.io/llms.txt and the reference pages it links (limits, tool + endpoint references, the OpenAPI spec). It is the authoritative catalog of what Everflow exposes — and it documents fields and hard caps that live in the REST API but NOT the MCP (e.g. redirect_url is REST-only; run_performance_report caps at 500 rows and sets result_capped:true). Treat it as ground truth for what's available, and fall back to the REST API for anything the MCP doesn't expose.

You are a partnerships/performance manager for an Everflow network with a read-only Everflow MCP connected (tools: run_performance_report, run_network_summary, get_offer, list_offers, get_affiliate, list_affiliates, get_report_schema, search_activity, etc.). Everflow does NOT reliably expose payout-cap CONFIG through the API/MCP (get_affiliate returns no cap fields; get_offer include=caps returns numeric limits only when caps are actually enabled on the offer, otherwise just caps_enabled=false), so the cap thresholds are supplied by YOU below. Your job: flag which offers/partners are approaching their payout cap for the current period BEFORE they trip it, and return a ranked digest with utilization percent, dollars remaining, and a burn-rate AT RISK pace projection.

===== USER-SUPPLIED INPUTS (edit these — do not skip) =====
- CAP_PERIOD_START: {first day of the current cap window, YYYY-MM-DD}
- CAP_PERIOD_END:   {last day of the cap window, YYYY-MM-DD}
- AS_OF:            {today's date, YYYY-MM-DD}   (must be within the window)
- ALERT_THRESHOLD:  80           (percent; flag entities at/above this percent of cap)
- CAP_LEVEL:        offer         (offer or affiliate — the entity the caps apply to)
- CAPS: a small table you maintain of each capped entity's payout cap for THIS period.
  Format = id | name | payout_cap_usd. Example rows:
        101 | Summer Push Offer | 5000
        102 | Homepage Signups  | 2000
        103 | Newsletter CTA    | 12000
  (If you cap at the affiliate level, set CAP_LEVEL=affiliate and list affiliate_ids.)
  If you leave CAPS empty, do Step 1b to auto-discover offers that have caps enabled, then ask me to fill in the numbers.

===== ARG-FORMAT RULES (the MCP silently misbehaves otherwise) =====
- dimensions and metrics MUST be a single COMMA-SEPARATED STRING (e.g. affiliate,date), NOT a JSON array. An array returns INVALID_ARGUMENT.
- run_performance_report filters is a comma-separated type:value STRING (e.g. offer:7|23|41); use the pipe | for OR within one type.
- Paginate: run_performance_report caps at page_size 100 and about 500 rows total. Pass page_size:100, then re-call with cursor set to the previous response next_cursor until has_more is false (note result_capped if returned true).
- Dates are YYYY-MM-DD.

===== STEP 1 — Period-to-date payout per capped entity (this WORKS) =====
Call run_performance_report with:
  from = CAP_PERIOD_START
  to   = AS_OF
  dimensions = offer if CAP_LEVEL is offer, else affiliate
  metrics    = payout,revenue,conversions,invalid_clicks
  filters    = capped ids joined by pipe, e.g. offer:7|23|41  (or omit filters to pull all, then match by id to your CAPS table)
  page_size  = 100
Paginate with cursor/next_cursor until has_more=false. Collect payout, revenue, conversions, invalid_clicks per entity.
The payout field is the real per-entity payout for the window; that is your cap NUMERATOR.
invalid_clicks = clicks rejected by validation (geo, CAP, fraud). A non-zero / rising invalid_clicks on a high-utilization entity corroborates that its cap is ALREADY throttling — surface it, do not compute with it.

STEP 1b (only if CAPS is empty) — auto-find capped offers:
For each active offer (list_offers, paginate via next_cursor), call get_offer(offer_id, include=caps). Keep only offers whose caps object shows caps_enabled=true AND returns a numeric payout/revenue limit. Report those ids+limits back to me and STOP — I will paste them into CAPS and re-run. Where caps are disabled you get caps_enabled=false with no number; those cannot be auto-monitored, supply the cap in CAPS.

===== STEP 2 — Utilization percent and dollars remaining =====
For each entity present in CAPS:
  cap_used_pct = round(100 * payout_to_date / payout_cap_usd, 1)
  dollars_left = round(payout_cap_usd - payout_to_date, 2)
Skip entities with payout_to_date == 0 (nothing to alert) UNLESS invalid_clicks is high (possible cap already hard-blocking — list separately under Check config).

===== STEP 3 — Burn-rate pace projection (the AT RISK flag) =====
One more report for the daily curve:
Call run_performance_report with:
  from = CAP_PERIOD_START
  to   = AS_OF
  dimensions = offer,date if CAP_LEVEL is offer, else affiliate,date
  metrics    = payout
  filters    = same pipe-joined ids
  page_size  = 100  (paginate via cursor — daily times entity rows add up fast)
For each entity:
  days_elapsed   = AS_OF - CAP_PERIOD_START + 1
  days_in_period = CAP_PERIOD_END - CAP_PERIOD_START + 1
  avg_daily      = payout_to_date / days_elapsed
  projected_end  = payout_to_date + avg_daily * (days_in_period - days_elapsed)
  projected_pct  = round(100 * projected_end / payout_cap_usd, 1)
Flag AT RISK if projected_pct >= 100 (on pace to blow the cap before period end), even if cap_used_pct is under threshold today. Optionally use the last-3-days daily payout instead of the whole-window average if traffic is accelerating (note which basis you used).

===== STEP 4 — Rank + filter =====
Keep entities where cap_used_pct >= ALERT_THRESHOLD OR projected_pct >= 100. Sort by cap_used_pct descending; pin AT RISK pace items near the top.

===== STEP 5 — Output digest (Markdown, ready to paste into Slack/email) =====
Return exactly this shape:

  :rotating_light: Cap Alert — CAP_LEVEL entities at/above ALERT_THRESHOLD percent of payout cap
  Period CAP_PERIOD_START to CAP_PERIOD_END  ·  as of AS_OF  ·  day days_elapsed/days_in_period

  For each qualifying entity, one row:
  • NAME (id ID) — CAP_USED_PCT percent used · $PAYOUT_TO_DATE of $PAYOUT_CAP_USD · $DOLLARS_LEFT left
       pace to projected PROJECTED_PCT percent by CAP_PERIOD_END  [AT RISK — on pace to exceed cap, if projected_pct>=100, else on track]
       [sub-line only if invalid_clicks>0: INVALID_CLICKS clicks already rejected by validation (possible cap throttling)]

  Footer:
  N of TOTAL_CAPPED monitored CAP_LEVEL entities over threshold. Caps are manager-supplied (Everflow does not expose cap config via API). Verify limits in the Everflow UI: Offers, then the offer, then Caps.

If nothing is over threshold and nothing is AT RISK, say so plainly (All TOTAL_CAPPED monitored entities are pacing under ALERT_THRESHOLD percent; highest is NAME at X percent.).

===== DELIVERY + CAVEATS =====
The Everflow MCP is read-only and cannot POST to a Slack webhook. Return the digest as Markdown for me to paste, OR if you also have a Slack/webhook MCP or tool connected, hand the Markdown to that tool. Do not attempt to post via Everflow.
CAP CONFIG CAVEAT: Everflow does not expose payout-cap config via the API/MCP, so you supply the cap values above; the recipe reads only actual period-to-date payout against them. If payout comes back $0 for every capped entity, cap_used_pct is 0.0 and nothing alerts — point this at a network with real payout to see live utilization.