Boards API overview

A board is a custom analytics dashboard: a set of SQL-backed widgets, grouped into tabs, parameterised by filters your team can change without editing the query. This API does everything the dashboard does — discover the schema, develop a query, save it as a widget, run it, and schedule recurring delivery of the result.

For the dashboard walkthrough of the same concepts, see Boards under Monitor.

Base URL

https://apps.sarvam.ai/api/analytics/v1/{org_id}/{workspace_id}

Boards are workspace-scoped: board paths carry no app_id, and a board can query across every agent in the workspace.

Requests are authenticated with your API key, as everywhere else in the Voice Agents API — see Introduction.

Rate limits

Four limits apply, and a request must satisfy every one that covers it: a per-key limit on every boards endpoint, plus a per-organization limit on each of the three endpoints that run queries.

The per-organization limits are shared across every key and every user in the org — a colleague running queries in the dashboard consumes the same budget as your integration.

Exceeding any of them returns 429 with a Retry-After header giving the wait in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "detail": "Rate limit exceeded. Please wait before making more requests." }

Honour Retry-After rather than retrying immediately, and back off exponentially if you see repeated 429s. If your workload needs more headroom, higher limits can be provisioned per organization — contact Sarvam support.

How the pieces fit together

Filters are never created directly — that is why List filters and Update filter exist but “create filter” does not. A filter comes into being when a {{token}} appears in a widget’s SQL, and the board’s filter set is the union of the tokens across its widgets. See Writing board SQL.

Errors

Every error carries a detail field. For most failures it is a message string:

{ "detail": "Dashboard 0b7f2c9a-5e41-4d2a-9f3b-8c1d6e7a0b52 not found" }

Not-found messages call boards dashboards, and name the missing tab, widget, filter, or rule the same way.

For SQL and query-execution failures it is an object with a machine-readable code, so you can branch on the cause rather than parsing prose:

{ "detail": { "code": "FORBIDDEN_TABLE", "message": "Table `users` is not available." } }

Request validation failures — a malformed UUID in the path, or a field outside its limits — return 422 with detail as a list of errors. The run endpoints also use 422 for CLICKHOUSE_ERROR, where detail is an object, so check whether detail is a list before reading code.

The full code table is on Writing board SQL.

What this API does not do

These are deliberate, not gaps to work around:

• No deletion. There are no DELETE routes. Boards, tabs, widgets, and notification rules are created and edited through the API but removed only in the dashboard.
• No CSV export. Widget downloads are a dashboard feature. Read results as JSON from the run endpoints.
• No whole-board run. The tab is the unit — call Run tab once per tab.
• No AI query generation. Generating SQL from a plain-language prompt is dashboard-only.

Next