ApexCloud Retention Operations
API-driven skill for the ApexCloud Retention Operations service. Use this when
the task requires calling the API to pull account, financial, and operational
data and assembling a structured JSON response with controlled labels,
deterministic precision, and policy codes.
Base URL
The task prompt always provides the base URL as <TASK_ENV_BASE_URL>. Replace
that token with the actual URL from the task before making any requests. All
endpoints are GET only and require no authentication.
Endpoint Catalog
| Endpoint |
Key shape |
Notes |
GET /api/accounts |
.accounts[] — list of all account profiles |
Full-account list for cross-portfolio work |
GET /api/accounts/{id} |
Single account object |
Profile detail for one account |
GET /api/accounts/{id}/metrics?start=YYYY-MM&end=YYYY-MM |
.metrics[] — monthly metric rows |
Revenue, SLA, NPS, usage, seats per month |
GET /api/accounts/{id}/tickets?start=YYYY-MM-DD&end=YYYY-MM-DD |
.tickets[] — support ticket records |
SLA fields, severity, status, is_duplicate, is_spam |
GET /api/accounts/{id}/nps?start=YYYY-MM-DD&end=YYYY-MM-DD |
.nps_responses[] — NPS survey records |
score, retracted flag, survey_channel |
GET /api/billing/snapshots |
.snapshots[] — quarterly billing snapshots |
billing_arr, mrr, as_of date |
GET /api/finance/ar-aging |
.ar_aging[] — AR aging by quarter |
current, 1_30, 31_60, 61_90, 90_plus buckets |
GET /api/opportunities |
.opportunities[] — CRM pipeline |
stage, state, amount, close_date, product_line |
GET /api/hr/summary |
.hr_summary[] — HR ops by region/quarter |
headcount, unpaid_claims, open_advances |
GET /api/events/performance |
.event_performance[] — event ops by event/quarter |
event_revenue, event_orders, product_revenue |
GET /exports/churn/train.csv |
CSV — churn training data |
19 features + Churn label |
GET /exports/churn/validation.csv |
CSV — churn validation data |
Same schema as train.csv |
GET /exports/churn/candidates.csv |
CSV — candidate accounts for scoring |
Same features, no Churn label |
GET /exports/account_metric_extract.csv |
CSV — normalized metric time series |
account-level monthly metrics across all periods |
Full field schemas for every endpoint are in
references/api_reference.md.
Precision Rules
Follow these output conventions exactly unless the task prompt overrides a
specific format:
- Currency (ARR, revenue, overdue balance, pipeline amounts): 2 decimal
places, e.g.
1416439.47
- Percentages (SLA compliance, win rate, accuracy): 1 decimal place,
e.g.
93.3
- Churn probabilities: 3 decimal places, e.g.
0.102
- Counts (tickets, accounts, headcount, orders): integers
- Risk scores: integers
- NPS scores: integers (null when no survey response exists)
- Months:
YYYY-MM format (e.g. 2026-04)
- Dates:
YYYY-MM-DD format (e.g. 2026-07-22)
Controlled Vocabulary
Every task requires picking values from a fixed controlled vocabulary. The
complete catalog with all enum labels is in
references/controlled_vocabulary.md. Load
it at the start of every task so you never invent a label.
Key categories:
- risk_level:
critical, high, medium, low
- primary_action:
executive_qbr, collections_followup,
technical_recovery, renewal_save, nurture_monitor, no_action
- reason_codes:
overdue_receivable, low_tenure_high_churn,
sla_degradation, nps_drop, usage_decline, renewal_window,
expansion_offset, clean_billings
- policy_codes: multi-code groups — pick exactly one code per group after
assessing the data shape (see controlled vocabulary reference for the full
list and matching guidance)
Task Type Patterns
The API supports five core task patterns. See
references/workflows.md for step-by-step recipes for
each one:
- Renewal Risk Queue — Cross-account ranking by composite retention risk
- QBR Metrics Packet — Single-account quarterly business review data
- Receivables & Pipeline Operations Review — AR aging to CRM linking to
pipeline summary to HR/event context
- Churn Model Validation & Outreach Ranking — Validate model exports, rank
candidate accounts by churn probability
- High-Touch Retention Action Board — Full-portfolio retention board with
segment summaries and follow-up calendar
General Workflow
- Read the task prompt to identify which task type, which accounts, which
period, and which output shape is required.
- Read references/controlled_vocabulary.md
to load the full controlled-label catalog.
- Read references/workflows.md and follow the
recipe for the identified task type.
- Fetch only the endpoints needed for the specific task — never pull
unnecessary data.
- Compute derived values from API responses using the formulas in the workflow
recipe (e.g., clean ticket count = tickets minus duplicates and spam;
overdue balance = sum of aging buckets beyond current).
- Assemble the response JSON following the exact shape and enum constraints
from the task template.
- Apply deterministic precision rules from the Precision Rules section
unless the task overrides a specific rule.
Policy Codes
Every task includes a policy_codes object. Pick one code per key by matching
the data characteristics to the code descriptions in
references/controlled_vocabulary.md. Do
not guess — each code maps to a specific observable condition in the API
responses.
Important Constraints
- Never invent enum values or policy codes not listed in the controlled
vocabulary.
- Return only valid JSON — no markdown wrappers, no commentary outside the JSON
structure.
- When a task provides an answer template in
input/payloads/answer_template.json, match its structure exactly, filling
every required field.
- The
/api/accounts/{id}/billing and /api/accounts/{id}/ar-aging endpoints
do not exist — use /api/billing/snapshots and /api/finance/ar-aging
instead and filter by account/quarter.
- When counting "clean tickets", exclude tickets where
is_duplicate or
is_spam is true.
- NPS
latest_nps means the most recent non-null, non-retracted score in the
period. If none exists, use null or 0 as specified by the task template.
- Overdue balance for AR aging =
1_30 + 31_60 + 61_90 + 90_plus (sum of all
non-current buckets). Do not include the current bucket.
- The
billing_arr_current field on the account profile is the current billing
ARR. The CRM crm_arr field is the CRM-reported ARR. When a task asks for
current_arr, prefer billing_arr from the latest billing snapshot matching
the assessment date unless the task specifies otherwise.
- When linking AR customers to CRM accounts, match
customer_name from AR aging
against legal_name or account_aliases from the accounts list. If no match
is found, set link_status to "unlinked" and account_id to null.
1---2name: apexcloud-retention-ops-263description: ApexCloud Retention Operations API client for customer success and revenue operations workflows. Use when the task involves pulling data from the ApexCloud Retention Ops API (account profiles, metrics, support tickets, NPS, billing snapshots, AR aging, opportunities, HR summary, event performance, churn exports, or account metric extracts) to build structured deliverables such as renewal risk queues, QBR metrics packets, AR and pipeline operations reviews, churn model validation and outreach rankings, or high-touch retention action boards.4metadata:5 source: https://skillmd.com/skills/prism-shadow/apexcloud-retention-ops-266---78# ApexCloud Retention Operations910API-driven skill for the ApexCloud Retention Operations service. Use this when11the task requires calling the API to pull account, financial, and operational12data and assembling a structured JSON response with controlled labels,13deterministic precision, and policy codes.1415## Base URL1617The task prompt always provides the base URL as `<TASK_ENV_BASE_URL>`. Replace18that token with the actual URL from the task before making any requests. All19endpoints are `GET` only and require no authentication.2021## Endpoint Catalog2223| Endpoint | Key shape | Notes |24|---|---|---|25| `GET /api/accounts` | `.accounts[]` — list of all account profiles | Full-account list for cross-portfolio work |26| `GET /api/accounts/{id}` | Single account object | Profile detail for one account |27| `GET /api/accounts/{id}/metrics?start=YYYY-MM&end=YYYY-MM` | `.metrics[]` — monthly metric rows | Revenue, SLA, NPS, usage, seats per month |28| `GET /api/accounts/{id}/tickets?start=YYYY-MM-DD&end=YYYY-MM-DD` | `.tickets[]` — support ticket records | SLA fields, severity, status, is_duplicate, is_spam |29| `GET /api/accounts/{id}/nps?start=YYYY-MM-DD&end=YYYY-MM-DD` | `.nps_responses[]` — NPS survey records | score, retracted flag, survey_channel |30| `GET /api/billing/snapshots` | `.snapshots[]` — quarterly billing snapshots | billing_arr, mrr, as_of date |31| `GET /api/finance/ar-aging` | `.ar_aging[]` — AR aging by quarter | current, 1_30, 31_60, 61_90, 90_plus buckets |32| `GET /api/opportunities` | `.opportunities[]` — CRM pipeline | stage, state, amount, close_date, product_line |33| `GET /api/hr/summary` | `.hr_summary[]` — HR ops by region/quarter | headcount, unpaid_claims, open_advances |34| `GET /api/events/performance` | `.event_performance[]` — event ops by event/quarter | event_revenue, event_orders, product_revenue |35| `GET /exports/churn/train.csv` | CSV — churn training data | 19 features + Churn label |36| `GET /exports/churn/validation.csv` | CSV — churn validation data | Same schema as train.csv |37| `GET /exports/churn/candidates.csv` | CSV — candidate accounts for scoring | Same features, no Churn label |38| `GET /exports/account_metric_extract.csv` | CSV — normalized metric time series | account-level monthly metrics across all periods |3940Full field schemas for every endpoint are in41[references/api_reference.md](references/api_reference.md).4243## Precision Rules4445Follow these output conventions exactly unless the task prompt overrides a46specific format:4748- **Currency** (ARR, revenue, overdue balance, pipeline amounts): 2 decimal49 places, e.g. `1416439.47`50- **Percentages** (SLA compliance, win rate, accuracy): 1 decimal place,51 e.g. `93.3`52- **Churn probabilities**: 3 decimal places, e.g. `0.102`53- **Counts** (tickets, accounts, headcount, orders): integers54- **Risk scores**: integers55- **NPS scores**: integers (null when no survey response exists)56- **Months**: `YYYY-MM` format (e.g. `2026-04`)57- **Dates**: `YYYY-MM-DD` format (e.g. `2026-07-22`)5859## Controlled Vocabulary6061Every task requires picking values from a fixed controlled vocabulary. The62complete catalog with all enum labels is in63[references/controlled_vocabulary.md](references/controlled_vocabulary.md). Load64it at the start of every task so you never invent a label.6566Key categories:6768- **risk_level**: `critical`, `high`, `medium`, `low`69- **primary_action**: `executive_qbr`, `collections_followup`,70 `technical_recovery`, `renewal_save`, `nurture_monitor`, `no_action`71- **reason_codes**: `overdue_receivable`, `low_tenure_high_churn`,72 `sla_degradation`, `nps_drop`, `usage_decline`, `renewal_window`,73 `expansion_offset`, `clean_billings`74- **policy_codes**: multi-code groups — pick exactly one code per group after75 assessing the data shape (see controlled vocabulary reference for the full76 list and matching guidance)7778## Task Type Patterns7980The API supports five core task patterns. See81[references/workflows.md](references/workflows.md) for step-by-step recipes for82each one:83841. **Renewal Risk Queue** — Cross-account ranking by composite retention risk852. **QBR Metrics Packet** — Single-account quarterly business review data863. **Receivables & Pipeline Operations Review** — AR aging to CRM linking to87 pipeline summary to HR/event context884. **Churn Model Validation & Outreach Ranking** — Validate model exports, rank89 candidate accounts by churn probability905. **High-Touch Retention Action Board** — Full-portfolio retention board with91 segment summaries and follow-up calendar9293## General Workflow94951. Read the task prompt to identify which task type, which accounts, which96 period, and which output shape is required.972. Read [references/controlled_vocabulary.md](references/controlled_vocabulary.md)98 to load the full controlled-label catalog.993. Read [references/workflows.md](references/workflows.md) and follow the100 recipe for the identified task type.1014. Fetch only the endpoints needed for the specific task — never pull102 unnecessary data.1035. Compute derived values from API responses using the formulas in the workflow104 recipe (e.g., clean ticket count = tickets minus duplicates and spam;105 overdue balance = sum of aging buckets beyond current).1066. Assemble the response JSON following the exact shape and enum constraints107 from the task template.1087. Apply deterministic precision rules from the **Precision Rules** section109 unless the task overrides a specific rule.110111## Policy Codes112113Every task includes a `policy_codes` object. Pick one code per key by matching114the data characteristics to the code descriptions in115[references/controlled_vocabulary.md](references/controlled_vocabulary.md). Do116not guess — each code maps to a specific observable condition in the API117responses.118119## Important Constraints120121- Never invent enum values or policy codes not listed in the controlled122 vocabulary.123- Return only valid JSON — no markdown wrappers, no commentary outside the JSON124 structure.125- When a task provides an answer template in126 `input/payloads/answer_template.json`, match its structure exactly, filling127 every required field.128- The `/api/accounts/{id}/billing` and `/api/accounts/{id}/ar-aging` endpoints129 do not exist — use `/api/billing/snapshots` and `/api/finance/ar-aging`130 instead and filter by account/quarter.131- When counting "clean tickets", exclude tickets where `is_duplicate` or132 `is_spam` is true.133- NPS `latest_nps` means the most recent non-null, non-retracted score in the134 period. If none exists, use null or 0 as specified by the task template.135- Overdue balance for AR aging = `1_30 + 31_60 + 61_90 + 90_plus` (sum of all136 non-current buckets). Do not include the `current` bucket.137- The `billing_arr_current` field on the account profile is the current billing138 ARR. The CRM `crm_arr` field is the CRM-reported ARR. When a task asks for139 `current_arr`, prefer `billing_arr` from the latest billing snapshot matching140 the assessment date unless the task specifies otherwise.141- When linking AR customers to CRM accounts, match `customer_name` from AR aging142 against `legal_name` or `account_aliases` from the accounts list. If no match143 is found, set `link_status` to `"unlinked"` and `account_id` to `null`.