Dashboards - Read Widget Layout

Endpoint

/o/dashboards/widget-layout

Overview

Returns layout metadata (position, size) for all widgets linked to a dashboard.

Authentication

Pass api_key or auth_token as a query parameter, or send countly-token as a header. See Authentication.

Permissions

This endpoint requires authenticated user context but does not enforce dashboard sharing access checks.

Request Parameters

Parameter	Type	Required	Description
dashboard_id	String	Yes	Dashboard ID used to fetch widget references.
api_key	String	Conditional	Required if auth_token is not provided.
auth_token	String	Conditional	Required if api_key is not provided.

Examples

Read widget layout for one dashboard

/o/dashboards/widget-layout?
  dashboard_id=65e1f3d2a4f41a5f6f6d7701

Response

Success Response

[
  {
    "_id": "65e1f5f8a4f41a5f6f6d7703",
    "position": [0, 0],
    "size": [4, 3]
  }
]

Response Fields

Field	Type	Description
[]	Array	Root array of widget layout objects.
[]._id	String	Widget ID.
[].position	Array	Widget grid position.
[].size	Array	Widget dimensions.

Error Responses

This handler does not return explicit structured error payloads for dashboard lookup failures.

Behavior

Behavior Modes

Mode	Trigger	Processing Path	Response Shape
Layout read	Dashboard exists	Reads dashboard widget IDs and fetches layout fields from widgets collection.	Raw array of layout objects
Silent failure path	Dashboard read fails or dashboard missing	Handler currently does not send an explicit error response in this branch.	No structured payload

Impact on Other Data

• Read-only endpoint; no writes.

Limitations

• The handler does not enforce dashboard view permissions.
• Dashboard lookup errors do not return a stable error payload from this route.

Related Endpoints

• Dashboards - Read Widget
• Dashboards - Read

Implementation details

Database Collections

Collection	Used for	Data touched by this endpoint
countly.members	Authentication	Reads current member record via authenticated-user validation before dashboard query.
countly.dashboards	Dashboard widget reference lookup	Reads dashboard widgets array.
countly.widgets	Layout metadata lookup	Reads _id, position, and size for referenced widgets.