Skip to main content
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

# 1. Upload the workbook
upload = requests.post(
    f"{API}/files",
    headers={"X-API-Key": KEY},
    files={"file": open("q3_actuals.xlsx", "rb")},
    data={"purpose": "reference"},
).json()

# 2. Ask a question
resp = requests.post(
    f"{API}/excel/analyze",
    headers={"X-API-Key": KEY},
    json={
        "file_id": upload["file_id"],
        "prompt": "What was total Q3 revenue across all regions? Show the breakdown.",
    },
)
print(resp.json())
Response: 
{
  "run_id": "analyze_abc123",
  "answer": "Total Q3 revenue was $4.2M across 12 regions. Breakdown:\n- North: $1.1M\n- South: $980K\n- West: $1.3M\n- East: $820K",
  "tool_calls": 3,
  "duration_ms": 8421,
  "credits_used": 12
}

​
How it differs from /generate

/excel/generate/excel/analyze
Produces a fileYes (download_url)No
Modeaction (writes)ask (read-only)
ReturnsFile + summaryFree-form text answer
Creates a run rowYesNo (ephemeral)
Typical cost20–200 credits5–20 credits
Typical latency15–60s3–15s

​
Prompt patterns

“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?”
“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?”
“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).”
“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 same INSPECT_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
Other formats return 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/generate with 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.