---
title: "Evaluate a formula expression"
method: POST
path: "/api/sheets/evaluate-formula"
tags: ["Sheets formulas"]
---

# Evaluate a formula expression

`POST /api/sheets/evaluate-formula`

## Request

- Base URL: `https://trydock.ai`
- URL: `https://trydock.ai/api/sheets/evaluate-formula`
- Auth: HTTP bearer

Two modes:

- **Standalone** — body `{ formula }` only. Public. Evaluates against an empty grid. Useful for `=SUM(1, 2, 3)` style sanity checks.
- **In workspace** — body `{ formula, workspaceSlug, at? }`. Loads the workspace's columns + rows, evaluates the formula as if pasted into `at` (or the first cell if omitted), resolves references against actual data. Requires read access to the workspace.

Returns `{ ok, displayValue, error? }`.

## Request body

- object
  - `formula` string, required
  - `workspaceSlug` string: Workspace slug. Pass to evaluate against real data; omit for standalone.
  - `at` object: Optional anchor cell (only used with workspaceSlug).
    - `rowId` string, required
    - `colKey` string, required

## Response `200`

Evaluation result.

- object
  - `ok` boolean, required
  - `displayValue` string, required: The string the UI would render in the cell (matches HyperFormula's display, e.g. '60', '4.20', '#DIV/0!').
  - `error` object
    - `code` string, required
    - `summary` string, required

## Other responses

- `400`: Workspace has no columns, or anchor cell invalid.
- `401`: In-workspace mode + unauthenticated + private workspace.
- `404`: Workspace, row, or column not found.

---

[API](https://skmtc.dev/trydock/apis/dock-rest-api.md) - [All operations](https://skmtc.dev/trydock/apis/dock-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trydock/apis/dock-rest-api/revisions/dd96ae96a412?raw)