Dashboard Widget Objects

Dashboard widget objects are database documents that define data visualizations. Each widget has a unique _id used to export data via REST API.

Widget Types

Type	Description
`barChart`	Vertical or horizontal bar charts
`pieChart`	Pie or doughnut charts
`line`	Line graph visualizations
`pivotNumbers`	Multi-value numeric displays with breakdowns
`pivotTable`	Tabular pivot data

Getting the Dashboard Widget Id

Chart and Pivot widgets will have a "Copy widget id" located top right of the widget within the vertical 3 dot dropdown.
Copy this widget id of the dashboard and use this id value in your path param.

API Endpoints

Export Widget Data (CSV)

Exports widget data as CSV files. Supported for all widget types.

Endpoint: GET /api/v2/dashboard-widgets/{widgetId}/export

Query Parameters:

widgetId (required): Widget _id from the database
type (optional): default or detailed (default: default)
format (optional): csv (default: csv)
api_key (required): User API key

Response:

{
  "fileUrl": "https://example.com/downloads/widget-export.csv",
  "metadata": {
    "widgetType": "barChart",
    "exportType": "detailed",
    "format": "csv"
  }
}

Example:

curl -X GET \
  "https://app.hive.com/api/v2/dashboard-widgets/abc123xyz/export?type=detailed" \
  -H "api_key: your_api_key"

Get Widget Data (JSON)

Returns widget data as JSON for programmatic access. Only supported for barChart, pieChart, and line types.

Not available for pivotTable or pivotNumbers - use export endpoint instead.

Endpoint: GET /api/v2/dashboard-widgets/{widgetId}/data

Query Parameters:

widgetId (required): Widget _id from the database
workspace_id (required): Workspace identifier
user_filter_id (optional): Specific filter configuration
api_key (required): User API key

Example:

curl -X GET \
  "https://app.hive.com/api/v2/dashboard-widgets/abc123xyz/data?workspace_id=ws789" \
  -H "api_key: your_api_key"

Object Structure

Core Properties

Property	Type	Description
`_id`	string	Unique identifier for API requests
`type`	string	Widget type (`barChart`, `pieChart`, `line`, `pivotNumbers`, `pivotTable`)
`workspaceId`	string	Associated workspace ID
`title`	string	Widget display title
`deleted`	boolean	Soft delete flag

Data Configuration

Property	Type	Description
`reportOn`	string	Data source: `actions`, `projects`, `time`, `goals`
`XAxis`	string	Primary dimension (e.g., `projectNames`, `projectStatuses`)
`XAxisCustomFieldId`	string	Custom field ID for X-axis
`YAxis`	string	Metric (e.g., `countOfActions`, `estimatedTime`, `projectBudget`)
`YAxisCustomFieldId`	string	Custom field ID for Y-axis
`aggFunc`	string	Aggregation: `sum`, `count`, `avg`, `min`, `max`

Display Options

Property	Type	Description
`chartType`	string	Visual type: `verticalBar`, `horizontalBar`, `pie`, `doughnut`, `lineGraph`
`sort`	string	Sort order: `ascending`, `descending`
`showTitles`	boolean	Display axis titles
`showLegend`	boolean	Display legend
`legendPosition`	string	Legend placement: `top`, `bottom`, `left`, `right`
`showValueLabels`	boolean	Display values on data points
`displayGroupsAs`	string	Pivot layout: `rows`, `columns`

Example Objects

Bar Chart

{
  "_id": "abc123xyz",
  "type": "barChart",
  "workspaceId": "ws789",
  "title": "Budget by Project",
  "reportOn": "projects",
  "chartType": "verticalBar",
  "XAxis": "projectNames",
  "YAxis": "projectBudget",
  "aggFunc": "sum",
  "sort": "descending",
  "showLegend": false,
  "groupOthers": {
    "type": "firstN",
    "firstN": 15,
    "showOthers": false
  }
}

Pivot Table

{
  "_id": "def456ghi",
  "type": "pivotTable",
  "workspaceId": "ws789",
  "title": "Time Analysis",
  "reportOn": "time",
  "XAxis": "projects",
  "YAxis": "estimatedTime",
  "aggFunc": "sum",
  "displayGroupsAs": "rows",
  "showRowTotals": false,
  "showColumnTotals": false
}

Number Widget

{
  "_id": "ghi789jkl",
  "type": "pivotNumbers",
  "workspaceId": "ws789",
  "title": "Project Count by Status",
  "reportOn": "projects",
  "XAxis": "projectStatuses",
  "YAxis": "countOfProjects",
  "aggFunc": "sum",
  "titleSize": "H3",
  "truncateLongNumbers": false,
  "timeUnitsType": "hours"
}

Authentication

Include your API key via header or query parameter:

-H "api_key: your_api_key"
# or
?api_key=your_api_key

Generate API keys in your Hive workspace settings.

Error Codes

Code	Description
400	Invalid parameters or unsupported widget type
401	Missing or invalid API key
404	Widget not found
504	Export timeout (large datasets)

Notes

CSV exports may take up to 15 minutes for large datasets
Dashboard-level filters apply unless ignoreContainerFilter is true
Deleted widgets cannot be exported
pivotTable and pivotNumbers widgets only support the /export endpoint
Chart widgets (barChart, pieChart, line) support both /export and /data endpoints