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

• Batch endpoint that fetches data for every non-deleted widget in a canvas, sorted by position
• For table widgets: returns a 10-row preview (fixed limit=10, offset=0)
• For chart widgets: returns all rows
• Per-widget DuckDB failures are captured and returned inline (success: false) — the overall request always returns 200
• SUPER_ADMIN can fetch data for any canvas (bypasses userId ownership check); regular users only see their own canvases
• If the canvas has no widgets, returns { widgets: [] } with 200

Flow

Mermaid editor

Test cases

Method & URL

GET v1/widgets/data

Request

Headers

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

Query

canvasId
  - Required
  - Type : <string>
  - MongoDB ObjectId (24 hex characters)
  - The canvas whose widgets to fetch data for

Body

Path parameter

Response

2xx

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

message
  - Type : null

data
  - Type : <object>

data.widgets
  - Type : <object>[]
  - One entry per widget in the canvas, in position order
  - Empty array if canvas has no widgets

data.widgets[].widgetId
  - Type : <string>
  - Widget identifier

data.widgets[].success
  - Type : <boolean>
  - true if DuckDB query succeeded, false if it failed

data.widgets[].rows
  - Type : <object>[]
  - Present when success is true
  - Query result rows (table: 10-row preview, chart: all rows)

data.widgets[].totalCount
  - Type : <number>
  - Present when success is true
  - Total matching rows (table: DB count, chart: rows.length)

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

data.widgets[].sql
  - Type : <string>
  - Present when success is true and the requesting user is Super Admin
  - The SQL query used to fetch data

data.widgets[].error
  - Type : <string>
  - Present when success is false
  - "Unable to load this widget's data"

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

data.widgets[].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 or missing canvasId)

404

success
  - Type : false (boolean)

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