POST /excel/analyze is the read-only variant of /excel/generate. It
runs the Excel agent in mode=ask against a previously-uploaded file
and returns a JSON answer — no document produced, no storage writes.
Use it for:
- Customer-facing Q&A (“what’s our Q3 revenue?” against an uploaded workbook)
- Summarization pipelines over structured data
- Checks and validations (“does this budget balance?”)
Quickstart
How it differs from /generate
Prompt patterns
Direct questions
Direct questions
“What’s the total revenue on the Income sheet?”“How many rows are in the Employees sheet?”“What’s the average salary for engineering roles?”
Cross-sheet reasoning
Cross-sheet reasoning
“Does cash on the Balance Sheet match the ending cash on the Cash Flow
Statement?”“Are there formulas that reference sheets that don’t exist?”“Which cells contain #REF! errors?”
Summaries
Summaries
“Summarize this spreadsheet in 3 bullet points.”“What’s the story the data tells? 2-paragraph narrative.”“Describe the structure of this workbook (sheets, columns, data types).”
Validations
Validations
“Are the quarterly totals on the Revenue sheet internally consistent
with the monthly breakdowns?”“Do the bonus calculations in column F correctly apply the 10% rule
from the Assumptions sheet?”
What the agent sees
Analyze uses the sameINSPECT_WORKBOOK, QUERY_DATA, ANALYZE_DATA
read actions the main agent uses. It gets the full structure: sheet
names, column headers, cell values, formulas, and conditional formatting.
It does NOT modify the workbook.
Supported inputs
.xlsx— primary format.xls— older Excel; agent reads via openpyxl.csv/.tsv— treated as a single-sheet workbook
400 invalid_request.
Limitations
- Answer length capped at ~2000 tokens. For very long answers, ask for a summary or request the analysis in multiple focused calls.
- No file output. If you want the analysis embedded in a new workbook,
use
/excel/generatewith a prompt like “create a summary workbook of this data”. - Citations aren’t structured — the agent mentions sheets and ranges in prose but doesn’t return a machine-readable citation list. Coming.