Dashboard Data

Retrieve structured data from your dashboard widgets — including card values, chart series, and table reports. This endpoint returns the same data that powers the dashboard UI, making it easy to integrate into your own tools and automations.

Request


POST /dashboard_data

Headers

Header	Value	Required
Content-Type	`application/json`	Yes
Authorization	`Bearer <your_token>`	Yes

Body Parameters

You must provide either cardsDashboardId or dashboardWidgetId — not both.

Parameter	Type	Description
`cardsDashboardId`	`number` or `string` or `null`	The ID of a dashboard. Returns data for all card widgets (Totals and Formulas).
`dashboardWidgetId`	`number` or `string` or `null`	The ID of an individual widget. Returns data for that specific widget.
`dateRange`	`object` or `null`	Optional. Overrides the dashboard’s default date range.

Note

You can find dashboard and widget IDs in the Metric app URL when viewing a dashboard or by inspecting widget settings.

Date Range Object

The dateRange parameter accepts different formats depending on the type of range you need:


{
  "type": "CustomDateRange",
  "startDate": "2026-01-01",
  "endDate": "2026-03-31"
}


{
  "type": "AllTimeDateRange"
}

Response

The response contains column definitions and a hierarchical data structure.

Top-Level Fields

Field	Type	Description
`columnInfos`	`array`	Definitions for each data column
`root`	`object`	The root data node with values

Column Info Object

Each entry in columnInfos describes a column:

Field	Type	Description
`id`	`string`	Unique column identifier
`name`	`string`	Display name of the column. For metric and formula columns, includes the date range label in parentheses (e.g., `"Total Revenue (Q1 2026)"`) when a date range is applied.
`valueType`	`object`	Type of value — see Value Types below
`grouping`	`array`	Grouping configuration (empty for ungrouped columns)
`currency`	`string`	Currency code (e.g., `"USD"`) when applicable
`isFieldColumn`	`boolean`	`true` if this column represents a data field
`isGroupingColumn`	`boolean`	`true` if this column is used for grouping rows

Value Types

The valueType object indicates how to interpret the column’s values:

Type	Value Format
`String`	Plain text string
`Number`	Numeric value (default: `0`)
`Hours`	Hours as a number (default: `0`)
`Percentage`	Percentage as a number (default: `0`)
`Amount`	`{ "amount": 0, "currency": "USD" }`
`Rate`	`{ "amount": 0, "currency": "USD" }`
`Select`	String identifier of a related object. The `valueType` includes an `options` array with `{ id, name }` entries — used for grouping columns on employees, projects, and tasks.

Data Node (Root and Subsections)

The root object and each subsection share the same structure:

Field	Type	Description
`id`	`string`	Node identifier
`values`	`object`	Key-value pairs mapping column IDs to values
`sectionColumnId`	`string` or `null`	Column that defines this section’s grouping
`prefix`	`string` or `null`	Label prefix for the section
`rows`	`array`	Data rows within this node (optional)
`subsections`	`array`	Nested subsections (optional)

Each row in rows contains:

Field	Type	Description
`id`	`string`	Row identifier
`values`	`object`	Key-value pairs mapping column IDs to values

Examples

Get All Dashboard Cards

Retrieve metric and formula card values for an entire dashboard:


{
  "cardsDashboardId": 123
}

Response:


{
  "columnInfos": [
    {
      "id": "widget_1",
      "name": "Total Revenue (This Year)",
      "valueType": { "type": "Amount" },
      "grouping": [],
      "currency": "USD",
      "isFieldColumn": false,
      "isGroupingColumn": false
    },
    {
      "id": "widget_2",
      "name": "Total Hours",
      "valueType": { "type": "Hours" },
      "grouping": [],
      "currency": null,
      "isFieldColumn": false,
      "isGroupingColumn": false
    }
  ],
  "root": {
    "id": "root",
    "values": {
      "widget_1": { "amount": 150000, "currency": "USD" },
      "widget_2": 1250.5
    },
    "sectionColumnId": null,
    "prefix": null
  }
}

Retrieve data for a specific chart, table, or card widget:


{
  "dashboardWidgetId": 456
}

Override the Date Range

Pass a custom date range to override the dashboard default:


{
  "dashboardWidgetId": 456,
  "dateRange": {
    "type": "CustomDateRange",
    "startDate": "2026-01-01",
    "endDate": "2026-03-31"
  }
}

The data returned depends on the type of widget being queried:

Total — Returns a single metric value (e.g., revenue, hours, count). Inherits dashboard filters when configured.
Formula — Returns a calculated value based on a formula combining other metrics.
Chart — Returns a time series grouped by day, week, month, quarter, or year. Includes one or more metric/formula series.
List — Returns rows of entity data. Supported list types: Projects, Deals, Employees, Tasks, Expenses, Invoices, Health Reports, and Employee Timesheets.
Report — Returns a structured report with row grouping, column grouping, and multiple metrics.

Filters and Date Ranges

Widgets that have “Use dashboard filters” enabled will automatically apply the dashboard’s global filters to their data.
Each widget can have its own date range. If no date range is set on the widget, it inherits the dashboard’s global date range.
You can override the date range at request time using the dateRange parameter — this takes priority over both the widget and dashboard date ranges.

Access Control

You can only retrieve data from dashboards that you have access to:

Dashboards you created
Dashboards shared with everyone in your organization
Dashboards explicitly shared with you