Run widget | Sarvam API Docs

import requests
url = "https://apps.sarvam.ai/api/analytics/v1/org_id/workspace_id/boards/board_id/widgets/widget_id/run"
payload = {
    "filter_values": {
        "agent_id": {
            "filter_type": "string",
            "value": "support-agent-v3"
        },
        "start_date": {
            "filter_type": "date",
            "value": "2026-09-01"
        }
    },
    "row_limit": 500
}
headers = {
    "X-API-Key": "<your-api-key>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "columns": [
    {
      "name": "day",
      "type": "Date"
    },
    {
      "name": "connected",
      "type": "UInt64"
    },
    {
      "name": "total",
      "type": "UInt64"
    }
  ],
  "rows": [
    [
      "2026-09-01",
      842,
      1104
    ],
    [
      "2026-09-02",
      915,
      1187
    ]
  ],
  "row_count": 2,
  "truncated": false,
  "execution_ms": 184
}

Executes the widget’s stored SQL with the board’s filter defaults, overridden by any filter_values supplied here. Results are cached briefly per widget, filter set and row limit; editing the widget invalidates its cache. Safe and side-effect free despite being a POST. Render a whole board by calling this once per widget.

Path parameters

org_idstringRequired

Organization ID

workspace_idstringRequired

Workspace ID

board_idstringRequiredformat: "uuid"

widget_idstringRequiredformat: "uuid"

Request

This endpoint expects an object.

filter_valuesmap from strings to objectsOptional

Values overriding the filters' stored defaults, keyed by token name

row_limitintegerOptional1-10000Defaults to 1000

Maximum rows returned. Optional — omit it for the default of 1000. A LIMIT inside your SQL can narrow the result further but never widens it past this. The result reports truncated when this cut the result short.

Response

Successful Response

columnslist of objects

Column metadata in result order; position N describes position N of every row

rowslist of lists of any

Row values as positional arrays aligned 1:1 with columns, not keyed objects

row_countinteger

Number of rows in rows, which is not the total matched when truncated

truncatedboolean

True when the result was cut short by row_limit

execution_msinteger

Query execution time in milliseconds, excluding network transfer

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

408

Request Timeout Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

Path parameters

Headers

Request

Response

Errors