Skip to navigation
Voice AgentsBoardsWidgets

Run widget

View as Markdown

Runs the widget’s saved SQL with the board’s filter defaults, overridden by any filter_values you send. Results are cached for 60 seconds. To render a whole tab, use Run tab.

Path parameters

org_idstringRequired
Organization ID
workspace_idstringRequired
Workspace ID
board_idstringRequiredformat: "uuid"

Board ID, as returned in id by Create board or List boards. Must be a UUID; anything else is rejected with 422.

widget_idstringRequiredformat: "uuid"

Widget ID, from a tab’s widgets in Get board. Must be a UUID; anything else is rejected with 422.

Headers

X-API-KeystringRequired
Your workspace API key.

Request

This endpoint expects an object.
filter_valuesmap from strings to objectsOptional
Values overriding the filters' stored defaults, keyed by token name. Values for tokens the board has no filter for are ignored.
row_limitintegerOptional1-10000Defaults to 1000

Maximum rows, 1–10000. Default 1000. A LIMIT in your SQL also applies and is capped at 1000.

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 rows returned reached the row limit, so the result may have been cut. Also true when your own LIMIT is reached exactly.

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