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 plain-text answer in a JSON envelope — no document is produced, no storage writes happen. Use it when you want to query an existing spreadsheet without modifying it. Typical use cases include customer-facing Q&A over uploaded workbooks, summarization pipelines over structured data, and data validation checks (“does this budget balance?”, “are there any #REF! errors?”).

​
How it differs from /excel/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

​
Request parameters

​
file_id
string
required
The file_id of a previously uploaded .xlsx, .xls, or .csv file. You must upload the file first using POST /files (purpose: "reference") to get this ID.
​
prompt
string
required
Your natural-language question or instruction. Up to 5,000 characters. Be as specific as possible — reference sheet names, column headers, or cell ranges when you know them.

​
Step-by-step

1

Upload the workbook

Upload your .xlsx (or .csv) file and store the returned file_id. This is a one-time step — you can reuse the same file_id for multiple analyze calls.
import requests

API = "https://backend.overtenai.com/api/v1"
KEY = "sk_live_..."

with open("q3_actuals.xlsx", "rb") as f:
    upload = requests.post(
        f"{API}/files",
        headers={"Authorization": f"Bearer {KEY}"},
        files={"file": f},
        data={"purpose": "reference"},
    ).json()

file_id = upload["file_id"]
print(file_id)
2

Ask a question

Send the file_id and your question. The agent reads the workbook and returns an answer.
resp = requests.post(
    f"{API}/excel/analyze",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "file_id": file_id,
        "prompt": "What was total Q3 revenue across all regions? Show the breakdown.",
    },
)
print(resp.json())

​
Response shape

{
  "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
}
FieldDescription
answerFree-form text answer to your question. May include markdown formatting.
run_idAn ephemeral identifier for this analysis. Not reusable for follow-up turns.
tool_callsNumber of read operations the agent performed internally.
credits_usedCredits deducted for this call.
POST /excel/analyze does not produce a file and does not create a persistent run row. If you want the analysis embedded in a new workbook, use /excel/generate instead: “create a summary workbook of this data”.

​
Example prompts

Ask about specific values, totals, or counts:
  • "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?"
  • "What was total Q3 revenue across all regions?"

​
What the agent can see

The agent gets the full workbook structure: sheet names, column headers, cell values, formulas, and conditional formatting rules. It uses the same read actions as the generate endpoint — the key difference is that it never performs any write operations on the file.

​
Supported file formats

FormatNotes
.xlsxPrimary format — all features supported
.xlsOlder Excel format, read via openpyxl
.csv / .tsvTreated as a single-sheet workbook
Any other format returns 400 invalid_request.

​
Limitations

  • Answer length is capped at approximately 2,000 tokens. For very long answers, break your question into smaller, focused calls or ask for a summary first.
  • No structured citation list. The agent mentions sheet names and ranges in prose but does not return a machine-readable list of source cells.
  • No file output. This endpoint is read-only. To produce a document from the analysis, use POST /excel/generate.

​
Tips for better results

Reference specific sheet names and column headers when you know them. “What’s the total in column D of the Revenue sheet?” is faster and more accurate than “What’s the total revenue?”.
  • Reuse the same file_id for multiple questions — you only need to upload the file once.
  • For large workbooks, tell the agent which sheet to focus on to reduce unnecessary reads.
  • If you need a specific number format in the answer (e.g., “in millions with two decimal places”), include that in your prompt.
  • Excel guide — generate or edit workbooks with POST /excel/generate
  • Runs and tasks — run lifecycle and task polling
  • Credits — analyze calls cost 5–20 credits depending on workbook size