Visit Later

N/a

Related

• Chart & Table Response Spec — comprehensive guide for frontend rendering (chartConfig shapes per chart type, rows format, detection logic)

General Notes

• Executes the stored SQL query against DuckDB
• For tables: supports pagination via page/perPage (perPage enum: 10, 25, 50). Returns totalCount and a pageData object describing the current page
• For charts: returns all rows, totalCount equals rows.length, and pageData is null
• SUPER_ADMIN can fetch data for any widget (bypasses userId ownership check) and additionally receives data.sql; regular users only see their own widgets

Flow

Mermaid editor

Test cases

Method & URL

GET v1/widgets/:widgetId/data

Request

Headers

authorization
  - Required
  - Type : <string>
  - Bearer session token

Query

page
  - Optional
  - Type : <integer>
  - Min : 1
  - Default : 1
  - 1-indexed page number (applied only when widget.type = "table")

perPage
  - Optional
  - Type : <integer>
  - Enum : 10, 25, 50
  - Default : 10
  - Number of rows per page (applied only when widget.type = "table")

Body

Path parameter

widgetId
  - Required
  - Type : <string>
  - MongoDB ObjectId (24 hex characters)

Response

2xx

success
  - Type : true (boolean)
  - This indicates that request was executed successfully

message
  - Type : null

data
  - Type : <object>

data.rows
  - Type : <object>[]
  - Query result rows from DuckDB

data.totalCount
  - Type : <number>
  - Total matching rows (for tables: DB count for pagination, for charts: rows.length)

data.pageData
  - Type : <object> | null
  - Pagination metadata. Populated when widget.type is "table", null when widget.type is "chart"

data.pageData.current
  - Type : <integer>
  - The current (1-indexed) page number

data.pageData.last
  - Type : <integer>
  - The last page number (ceil(totalCount / perPage))

data.pageData.perPage
  - Type : <integer>
  - Number of rows per page actually applied

data.pageData.allowedPerPage
  - Type : <integer>[]
  - List of allowed perPage values (10, 25, 50)

data.columns
  - Type : <object>[] | null
  - Array of { field, label } objects defining table columns
  - Populated when widget.type is "table", null when widget.type is "chart"

data.sql
  - Type : <string>
  - The SQL query used to fetch data
  - Only included for Super Admin users

data.latestExplanation
  - Type : <string> | null
  - Plain-language explanation of the chart. Populated for type: "chart" only; always null for type: "table"

data.latestExplanationGeneratedAt
  - Type : <string> (ISO timestamp) | null
  - When the explanation was generated

400

success
  - Type : false (boolean)

message
  - Type : <string>
  - "Something went wrong. We're on it." (invalid widgetId format or invalid page/perPage)

404

success
  - Type : false (boolean)

message
  - Type : <string>
  - "Something went wrong. We're on it." (widget not found or IDOR)

500

success
  - Type : false (boolean)

message
  - Type : <string>
  - "Something went wrong. We're on it." (DuckDB query execution failure)