Ask in plain English

The assistant answers questions about your book in plain English — no filters to click, no query language to learn. Ask the way you’d ask a teammate (“how many members did Humana lose last month?”) and get the number back, with the underlying rows attached so every answer is auditable. Every answer is produced by a frontier AI model — on every account, no setup — while the numbers themselves always come from the same deterministic engines that power the report pages.

It is read-only and scoped to your account’s own data — it can never modify anything or reach another account’s book.

It shows its work as it happens. Answers stream: in the app you see each stage (“Running the report…”, “Querying your book…”) and, on investigations, every step as it completes. (API clients can opt into the same stream — see Streaming below.)

Conversations are remembered. Close the tab, switch devices, come back tomorrow — the thread is still there, and long conversations keep their context (older turns are summarized into each new answer). Conversation history is stored in your account’s own isolated database, like the rest of your data; start a fresh thread anytime with + New chat.

The assistant also answers product questions — “how do I upload a statement?”, “what does owed coverage mean?” — in plain English, with links to the relevant docs. It routes each message automatically: questions about your data are answered from your book; how-to questions are answered from the product docs. The response’s intent field tells you which path was taken.

Report questions get special treatment — and the assistant is fluent in all of them. Ask about chargebacks (proof-out), payment gaps, unpaid members, statement coverage, your book summary, carrier scorecards, attrition trends, cumulative owed & chargeback history, statement quality, the Medicare rapid-disenrollment radar and renewal forecast, ACA book value, cohort retention, 1099 tallies, or what changed between two months — and the assistant answers from the same deterministic engines that power those report pages, not from a model-written query. The numbers in the answer are exactly the numbers on the report page, the matching rows come attached, and the response carries a reportPath linking to the full (filtered) report. (Questions on gated reports require the corresponding feature; the book-health reports work for every account.)

The assistant knows your account’s context. Before answering, it reads auto-detected data-coverage warnings (a statement month that’s missing or loaded only partially) plus any notes on your account — so if a number is distorted by a missing file, the answer says so instead of presenting the distortion as fact. You can manage what it knows yourself: the “What the assistant knows” panel on the Ask AI screen lists every active note, and you can add your own (“our Aetna book moved to a new agency in May 2026”) — it takes effect on the very next question.

It speaks first. Every time a statement finishes processing, the assistant composes a short brief — what the month looked like, what changed vs last month, what needs attention — shown at the top of the completion email and pinned on the Ask AI screen.

Watch a question. Any recovery answer can become a standing watch (“tell me if a never-paid chargeback ever appears”): the question is re-checked automatically after every statement you load, and you get an email only when the matching count grows. Manage watches from the chips on the Ask AI screen (up to 10).

Attach a statement. Drop a file into the chat (the paperclip) and the assistant tells you what it is before anything is ingested: the carrier it matches, whether the layout matches the mapping on file (with how many rows map and the dollars they carry), and which months you already have loaded. Confirm the carrier and month inline to ingest it through the normal pipeline — the statement brief then lands in the same conversation when processing finishes.

Investigate deeper. One click turns a quick answer into a multi-step investigation: the assistant runs several read-only queries and reports — cross-checking coverage before drawing conclusions — and answers with a visible trace of everything it checked. Bounded and read-only by construction; runs on your own key when BYOK is configured.

Ask a question

curl -X POST "https://api.commissionsight.com/v1/assistant/query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "question": "How many members did Humana lose last month, and what were they worth?" }'

Request

Field	Type	Notes
`question`	string	Required. Max 500 characters.
`history`	array	Optional. Prior turns `[{ "question": "...", "sql": "..." }]` so follow-ups resolve in context (e.g. “and the month before?”). The last few turns are used.
`conversationId`	string	Optional. A conversation id from a previous answer — the turn is appended to it and older context carries into the answer. Omit to start a new conversation (the response returns its id).

Streaming

Add ?stream=1 (or send Accept: text/event-stream) and the endpoint answers as Server-Sent Events: status events as the assistant works (“Running the report…”), step events during investigations (one per tool call), then a final event whose data is the exact JSON payload below. Without the opt-in, the response is plain JSON as always.

Response

{
  "question": "How many members did Humana lose last month, and what were they worth?",
  "intent": "book_query",        // book_query | recovery_query | product_support | action
  "answer": "Humana dropped 7 members in April — $1,240.00 in prior commission. Two had reappeared in March, so net churn is 5.",
  "sql": "SELECT ...",          // the exact read-only query used, for transparency/audit
  "columns": ["carrier", "dropped", "prior_commission"],
  "rows": [ { "carrier": "Humana", "dropped": 7, "prior_commission": 1240.0 } ],
  "truncated": false             // true if the result set was capped for size
}

Every answer comes back with rows (the data it used) and sql (the read-only query behind it), so the number is never a black box — you can drop the rows straight into a report or reconcile them against a statement.

Good questions to ask

About your book (answered from your data, with rows + SQL):

“Who dropped off this month, and what were they worth?”
“Top 5 carriers by commission this period.”
“Which members’ commission changed the most since January?”
“How has attrition trended over the last six months?”

About chargebacks, missing payments, and data coverage (answered by the report engines, with the rows and a link to the full report — chargeback/gap questions require the proof-out / payment-gaps features):

“Were my chargebacks actually paid first?”
“Which chargebacks have no payment on record?”
“Which months did Ambetter never pay me?”
“Show the payment gaps that were never caught up.”
“Which chargebacks took back more than one month at once?”
“Is my statement data complete? Am I missing any months?”
“Who on my roster did the carrier never pay me for?” (uses your saved Unpaid members roster)
“How is my book doing this month?” / “How much am I owed?”
“Which carrier is performing worst?” (carrier scorecards)
“What’s my attrition trend?” / “How much was I owed over the last year?”
“What’s my renewal forecast?” / “What’s my book worth?” / “How do my enrollment cohorts retain?”
“What did each carrier pay me in 2025?” (1099 tallies)
“What changed between January and March?”

About the product (answered from the docs, with citations):

“How do I upload a statement?”
“What does owed coverage mean?”
“How do I set up a rate schedule?”

When the answer comes from the docs, the response carries an intent of product_support and a citations array ([{ "title": "...", "url": "..." }]) instead of rows/sql.

Notes

A question over 500 characters returns 422. An empty question returns 422.
The intent field is one of book_query, recovery_query, product_support, or action. A recovery_query answer includes reportPath (the in-app report the numbers came from) and its rows use the report’s own columns instead of sql. “Do it for me” requests (e.g. “set up my rate schedules”) classify as action and point you to the two AI setup flows, both now live: Set up a carrier (upload a sample statement → AI builds the column mapping) and Draft rates with AI on the Rates page (paste a comp grid → AI drafts your rate schedule for review). See Set up a carrier with AI and Draft rates with AI.
If the assistant has been paused for your account, the endpoint returns 403 (ai_paused).
Results are read straight from the same scored dataset that powers the grid and the other API endpoints, so the assistant’s numbers always agree with GET /v1/reports/* and the member views.
The assistant is generally available on every account. Usage is metered per account per month; an optional monthly cap can be set by the CommissionSight team (off by default — the assistant is uncapped unless a cap is configured). When a configured cap is reached the endpoint returns 402 (ai_cap_reached).
Bring your own key (BYOK) — now enabled for every account. Add your own OpenAI-compatible or Anthropic API key (with a model) in app → Profile. When set, Ask AI runs on your provider with your key and model choice — billed by them, with no monthly cap. The key is stored encrypted, never shown again (only provider/model/last-4), and never leaves CommissionSight except in the request to your chosen provider. Remove it anytime to revert to the built-in models — the assistant is frontier-quality either way.