> ## Documentation Index
> Fetch the complete documentation index at: https://nayax-44d6e37b-docs-marshall-faq-redistribution.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Machine Widget Data (API)

The Widgets Dashboard APIs let you discover which widgets are available for a given screen and fetch the data for each individual widget.

## Prerequisites

Before making calls to the Widget API, you need to have:

* Access to the Lynx QA or Production environment
* A valid API token (See [Security & Token](/docs/manage-data-operations/lynx-api/security))
* [Machines](/reference/lynx/machines/get-specific-machine-basic-info) or [Operator](/docs/manage-data-operations/lynx-api/operator/index) IDs

## Base URL

```text theme={null}
https://<host>/v1/dashboard
```

<Note>
  If the server is configured with `UseBasePath: true`, all routes are prefixed with `/operational`:

  ```text theme={null}
  https://<host>/operational/v1/dashboard
  ```
</Note>

## Authentication

All endpoints require authentication via JWT bearer token. Include the token in every request:

```text theme={null}
Authorization: Bearer <YOUR_ACCESS_TOKEN>
```

See [Security & Token](/docs/manage-data-operations/lynx-api/security) for details on obtaining a token.

## Available Endpoints

The following endpoints are available. Select a card to view the full API reference.

<CardGroup cols={2}>
  <Card icon="grid" title="List Widgets for a Screen" href="/reference/lynx/report/get-available-widgets">
    Returns all widgets configured for a given screen type, including their IDs, names, and configurations.
  </Card>

  <Card icon="chart-line" title="Retrieve Widget Data" href="/reference/lynx/report/retrieve-widget-data">
    Fetches data for a specific widget with full filter support (date range, machine ID, etc.). **Recommended for most use cases.**
  </Card>
</CardGroup>

<Note>
  The GET simple variant (`GET /v1/dashboard/widget-data`) is not included in the API reference as it is not defined in the OpenAPI spec. Use the POST variant for filter support and full API reference coverage.
</Note>

## Typical Integration Flow

A standard integration follows three steps: discover available widgets, fetch their data with optional filters, then parse the response payload.

```text theme={null}
1. GET /v1/dashboard/widgets?screenTypeId=1
       → Discover available widgets and their widgetTypeId values

2. POST /v1/dashboard/get-widget-data  (recommended - supports filters)
   OR
   GET  /v1/dashboard/widget-data      (simple - no filter support)
       → Fetch widget data, optionally scoped by entity and filtered by date/machine

3. Parse the response:
   - widgetDetails.widgetConfig → rendering hints
   - data                       → actual data payload (structure varies per widget)
```

## Error Handling

The following HTTP status codes may be returned by the widget endpoints:

| HTTP Status | Cause                                                                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | Missing required field, invalid parameter value                                                                                               |
| `401`       | Missing or expired bearer token                                                                                                               |
| `403`       | Authenticated but missing the required permission key for this endpoint                                                                       |
| `500`       | Backend error - common causes: wrong `Content-Type` header (use `application/json`), invalid `widgetTypeId`, or an unrecognized filter format |

## Permissions

Each endpoint requires the authenticated user to have a specific menu permission assigned in Lynx. Permissions are checked by the `GetContext()` middleware on every request:

| Endpoint                             | Permission Key                | OAuth Scope   |
| ------------------------------------ | ----------------------------- | ------------- |
| `GET /v1/dashboard/widgets`          | `lynx_report_get_widgets`     | `report:read` |
| `POST /v1/dashboard/get-widget-data` | `lynx_report_get_widget_data` | `report:read` |
| `GET /v1/dashboard/widget-data`      | `lynx_report_get_widget`      | `report:read` |

<Note>
  `GET /v1/dashboard/widget-data` requires `lynx_report_get_widget`, which is separate from `lynx_report_get_widget_data` (the POST variant). If you have access to the POST endpoint but receive a `403` on the GET endpoint, request the `lynx_report_get_widget` permission in your Lynx role configuration.
</Note>