agents-store Dashboards & Widgets
NocoDB v3 has a built-in dashboarding layer. A Dashboard is a container; Widgets are the individual tiles inside it (charts, KPIs, text blocks, iframes). All operations are Meta API v3.
Endpoints
| Path | Method | Purpose |
|---|---|---|
/api/v3/meta/bases/{base_id}/dashboards |
GET |
List dashboards |
/api/v3/meta/bases/{base_id}/dashboards |
POST |
Create dashboard |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id} |
GET |
Get dashboard |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id} |
PATCH |
Update dashboard |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id} |
DELETE |
Delete dashboard |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/data |
GET |
Fetch all widget data for the dashboard |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets |
GET |
List widgets |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets |
POST |
Create widget |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets/{widget_id} |
GET |
Get widget |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets/{widget_id} |
PATCH |
Update widget |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets/{widget_id} |
DELETE |
Delete widget |
/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets/{widget_id}/data |
GET |
Fetch widget data |
Widget Types
Per the OpenAPI WidgetOptions* schemas:
type |
Schema | Use case |
|---|---|---|
metric |
WidgetOptionsMetric |
Single KPI tile (count / sum / avg) |
bar_chart |
WidgetOptionsBarChart |
Categorical bar chart |
line_chart |
WidgetOptionsLineChart |
Time-series line |
pie_chart |
WidgetOptionsPieChart |
Proportional pie |
donut_chart |
WidgetOptionsDonutChart |
Like pie, with hole |
text |
WidgetOptionsText |
Markdown content block |
iframe |
WidgetOptionsIframe |
Embedded URL |
Create a Dashboard
curl -sS -X POST \
-H "xc-token: $NOCODB_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "Sales Overview", "description": "Daily KPIs" }' \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards"
Response includes the new dashboard_id.
Add a Metric Widget
curl -sS -X POST \
-H "xc-token: $NOCODB_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Active Customers",
"type": "metric",
"options": {
"table_id": "<customersTableId>",
"aggregation": "count",
"filter": "(Status,eq,Active)"
}
}' \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards/$DASHBOARD_ID/widgets"
Add a Bar Chart Widget
curl -sS -X POST \
-H "xc-token: $NOCODB_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Revenue by Region",
"type": "bar_chart",
"options": {
"table_id": "<ordersTableId>",
"x_axis": { "field_id": "<regionFieldId>" },
"y_axis": { "field_id": "<amountFieldId>", "aggregation": "sum" }
}
}' \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards/$DASHBOARD_ID/widgets"
Probe the spec for the exact options shape per widget type:
jq '.components.schemas.WidgetOptionsBarChart' \ skills/api-reference/references/nocodb-meta-openapi.json
Fetch Widget Data
For one widget:
curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards/$DASHBOARD_ID/widgets/$WIDGET_ID/data"
For an entire dashboard (all widgets in one call):
curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards/$DASHBOARD_ID/data"
The dashboard-level /data endpoint runs every widget's query in parallel server-side and returns the consolidated payload — prefer this over N individual widget calls when rendering a dashboard view.
Update a Widget
curl -sS -X PATCH \
-H "xc-token: $NOCODB_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "Renamed", "options": { "filter": "(Status,eq,Premium)" } }' \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards/$DASHBOARD_ID/widgets/$WIDGET_ID"
Type-specific options keys depend on the widget kind — refer to the matching WidgetOptions* schema.
Delete a Widget / Dashboard
# Widget
curl -sS -X DELETE -H "xc-token: $NOCODB_API_TOKEN" \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards/$DASHBOARD_ID/widgets/$WIDGET_ID"
# Dashboard (deletes all widgets too)
curl -sS -X DELETE -H "xc-token: $NOCODB_API_TOKEN" \
"$NOCODB_URL/api/v3/meta/bases/$BASE_ID/dashboards/$DASHBOARD_ID"
Confirm with the user before deleting — both operations are unrecoverable.
Pre-Flight Checklist
| Widget kind | Pre-flight |
|---|---|
metric |
table_id set; aggregation is one of count / sum / avg / min / max; numeric field_id for non-count aggregations |
bar_chart / line_chart |
x_axis.field_id and y_axis.field_id reference existing columns; y_axis.aggregation matches the field type |
pie_chart / donut_chart |
One categorical field_id; one numeric field_id (or count) |
text |
Body markdown ≤ NocoDB's text limit |
iframe |
URL allowed by NocoDB's iframe-source allowlist (admin-controlled) |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| 422 on widget create | options missing required fields for that type |
Probe WidgetOptions<Type> schema and add the missing keys |
| Widget shows no data | filter excludes everything; field_id deleted |
Verify the field still exists and the filter matches some records |
Widget on iframe blocks loading |
URL not in allowlist | Admin must add the host to allowed iframe sources |
| Data endpoint slow | Many large widgets querying simultaneously | Reduce widget count or widen filters |
| 404 on widget | Widget deleted or wrong dashboard_id |
List widgets to confirm |
See Also
- api-reference skill — full Meta API v3 path reference
references/nocodb-meta-openapi.json— OpenAPI source of truth forWidgetOptions*schemas- field-management skill — fields used as widget axes / metrics must exist on the source table