Skip to main content
This page covers the field reference for widget parameters and filters used when calling the Widgets Dashboard API endpoints.

​
Field Reference

​
ScreenTypeId Values

screenTypeId identifies which dashboard screen context the widget belongs to:
ValueScreenDescription
1Reports / DashboardThe main operator-level reporting dashboard
2Operations / MachineThe machine-level operations screen
Use screenTypeId=1 for revenue, sales, and summary widgets. Use screenTypeId=2 for per-machine operational widgets.

​
EntityId

entityId scopes the widget data to a specific entity. The meaning depends on the widget type:
  • Operator-level widgets: pass the Operator ID (ActorID)
  • Machine-level widgets: pass the Machine ID
  • Omit or pass null to retrieve data across all entities the authenticated user has access to

​
WidgetTypeId

Obtain the list of valid widget type IDs for a given screen by calling: 
GET /v1/dashboard/widgets?screenTypeId=1
Each item in the response array contains widgetTypeId and widgetName. Use the name to identify which widget you need, then use its ID in subsequent data requests. The IDs are defined in the Cortex Reports service database and may vary by environment.
See the complete Widgets ID List for a reference table of all known widget IDs.
The Devzone reference page for “Retrieve Widget Data” uses widgetTypeId: 5 (“Top Events For Period”) in its example, but presents it as if it were a revenue widget. This is incorrect. Use GET /v1/dashboard/widgets to discover the correct widgetTypeId for revenue widgets in your environment (commonly ID 19).

​
Filter Names

Filter names are widget-specific. The following are commonly used across revenue and reporting widgets:
NameDescriptionExample Value
startDateStart of the date range (inclusive)"2025-01-01"
endDateEnd of the date range (inclusive)"2025-12-31"
TimePeriodPre-defined time period in days (alternative to date range)"30"
MachineIdFilter data for a specific machine"98765"
groupByGrouping granularity"day" / "month"
startDate/endDate and TimePeriod are mutually exclusive - providing both may result in an error. Use one approach per request.
MachineId via entityId vs filter: Some widgets accept the machine ID through the entityId field; others accept it as a MachineId filter entry. If the widget is scoped to the machine screen (screenTypeId=2), prefer entityId. If it is a dashboard widget (screenTypeId=1), use the MachineId filter. The exact behavior depends on the widget’s stored procedure implementation.

​
Filter Types

The type field in a filter is a hint used by the backend to parse the value string:
TypeDescription
"Date"ISO 8601 date string (YYYY-MM-DD)
"int"Integer value
"string"Free-text string

​
Multiple Filters in One Request

The filters field is an array - multiple filters can be combined in a single request. For example, filtering by date range, machine ID, and grouping in one call: 
{
  "screenTypeId": 1,
  "widgetTypeId": 19,
  "entityId": null,
  "filters": [
    { "name": "startDate", "value": "2025-01-01", "type": "Date"   },
    { "name": "endDate",   "value": "2025-12-31", "type": "Date"   },
    { "name": "MachineId", "value": "98765",      "type": "int"    },
    { "name": "groupBy",   "value": "day",        "type": "string" }
  ]
}
The filters are forwarded to the Cortex Reports service, which applies them in the stored procedure for that widget type.

​
Notes

  • The shape of the data field in WidgetDataResponseDto is dynamic and varies per widget type.
  • Widget type IDs are defined in the Cortex Reports service database and map to screen types via the widget_dashboard_compatibility column (ScreenTypeId).
  • The Lynx API acts as an authenticated pass-through proxy to Cortex Reports. It does not modify or validate filter contents beyond basic deserialization.