> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.overtenai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze (Excel)

> Ask natural-language questions of a spreadsheet and get a structured answer.

`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

```python theme={null}
# 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:

```json theme={null}
{
  "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 file   | Yes (download\_url) | No                    |
| Mode              | `action` (writes)   | `ask` (read-only)     |
| Returns           | File + summary      | Free-form text answer |
| Creates a run row | Yes                 | No (ephemeral)        |
| Typical cost      | 20–200 credits      | 5–20 credits          |
| Typical latency   | 15–60s              | 3–15s                 |

## Prompt patterns

<AccordionGroup>
  <Accordion title="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?"
  </Accordion>

  <Accordion title="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?"
  </Accordion>

  <Accordion title="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)."
  </Accordion>

  <Accordion title="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?"
  </Accordion>
</AccordionGroup>

## 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.