Dashboards API
API for creating, retrieving, updating, and deleting dashboards
Dashboards are groups of charts. In a dashboard, all the charts that belong to the dashboard appear at the same time and follow the same filtering options.
The system lays out dashboards and the charts they contain with these dimensions:
- The web UI reserves a 12x100 grid for each dashboard and assigns one or more charts to specific locations within the grid.
- A chart associated with the dashboard can be any size from 1x1 to 12x3.
- If you assign overlapping dashboard locations for charts, the system attempts to resize or reorganize the layout. This ensures that all of the charts fit within the space allotted to the dashboard.
By default, all users in an organization can edit and delete dashboards and dashboard groups. If the write permissions feature is available in your organization, you can limit editing or deleting of specific dashboards to specific individuals or teams, or both. Use this feature to prevent unauthorized or accidental modifications to dashboards and the charts they contain.
To learn more, see the topic "Setting Write Permissions" in the product documentation.
Users who don't have permission to edit a dashboard can still clone it and modify the clone.
To create a mirrored dashboard, use the Dashboard Groups API.
You can view dashboards you create using the API in the web UI by specifying their "id" property in a web UI URL, by following this syntax:
https://app.signalfx.com/#/dashboard/<DASHBOARD_ID>
Dashboards you create using the API also appear by name in the web UI catalog and in their dashboard group.
Retrieves dashboards based on search criteria
Retrieves one or more dashboard objects, based on query parameters you encode on the request URL. If you don't specify parameters, the request returns the first 50 objects that the user has access to, based on the user's access token specified in the request header. Query parameters also control the point in the result set at which the system starts returning objects, and the number of objects to return.
query Parameters
| limit | integer <int32> The maximum number of dashboards to return. If the value isn't valid, the system defaults to 50 dashboards. |
| name | string Search string that the system compares to existing dashboard names.
A match occurs if the string matches any part of the dashboard name.
For example, the query specification
If you specify The string must only contain ASCII characters. |
| offset | integer <int32> 0-based index of the point in the query results where the system starts returning dashboards. If the offset value is greater than the size of the result set, you don't receive any results. |
header Parameters
| Content-Type required | string Format of the request body. Always "application/json". |
| X-SF-TOKEN required | string Authentication token |
Responses
| Content-Type | string Format of the response body. Always "application/json". |
Response Schema: application/json
| count | integer <int32> Number of dashboards that matched the provided search criteria. NOTE: This value is the total number of
matches. The number of dashboards that the system returns
is affected by the
|
Array of objects List of dashboard objects that the system returns as the
result of the request. These objects represent dashboards
that match the search query. The number and location of
the objects within the result set depend on the query
parameters you specify in the request. To learn more, see
the top-level description of the API and the description
of the |
Response samples
- 200
{- "count": 0,
- "results": [
- {
- "authorizedWriters": {
- "teams": [
- "string"
], - "users": [
- "string"
]
}, - "chartDensity": "DEFAULT",
- "charts": [
- {
- "chartId": "string",
- "column": 0,
- "height": 1,
- "row": 0,
- "width": 1
}
], - "created": 0,
- "creator": "string",
- "customProperties": { },
- "description": "string",
- "discoveryOptions": { },
- "eventOverlays": [
- {
- "NOT": false,
- "property": "string",
- "value": [
- "string"
]
}
], - "filters": {
- "sources": [
- {
- "NOT": false,
- "property": "string",
- "value": [
- "string"
]
}
], - "time": {
- "end": "string",
- "start": "string"
}, - "variables": [
- {
- "alias": "string",
- "preferredSuggestions": [
- "string"
], - "property": "string",
- "required": false,
- "restricted": false,
- "value": [
- "string"
]
}
]
}, - "groupId": "string",
- "id": "string",
- "lastUpdated": 0,
- "lastUpdatedBy": "string",
- "maxDelayOverride": 0,
- "name": "string",
- "selectedEventOverlays": [
- {
- "eventColorIndex": 0,
- "eventLine": false,
- "eventSignal": {
- "eventSearchText": "string",
- "eventType": "detectorEvents"
}, - "label": "string",
- "overlayId": "string",
- "sources": [
- [
- {
- "NOT": false,
- "property": "string",
- "value": [
- "string"
]
}
]
]
}
], - "tags": [
- "string"
]
}
]
}Creates a single dashboard
Creates a dashboard using the properties specified in the request body. If the write permissions feature is available in your organization, you can specify the users and teams that who have permission to edit or delete the dashboard or its charts.
header Parameters
| Content-Type required | string Format of the request body. Always "application/json". |
| X-SF-TOKEN required | string Authentication token |
Request Body schema: application/json
Create dashboard request body
object (Organizations and teams with write permission for an object) If the write permissions feature is available for your organization, you can use these properties to specify the user and team IDs that have write access to the chart of dashboard. | |
| chartDensity | string (DashboardChartDensity) Default: "DEFAULT" Enum: "DEFAULT" "LOW" "HIGH" "HIGHEST" Controls the number of data points displayed in the charts for this dashboard, over the time span specified for the charts:
|
Array of objects (DashboardCharts) List of charts associated with the dashboard, in the form of a JSON array of JSON objects. Each chart must exist and be unique across all dashboards. | |
| description | string (DashboardDescription) Description of the dashboard. The system displays the value in the dashboard tab tooltip in the dashboard group in the web UI. |
Array of objects (DashboardEventOverlays) List of event overlay definitions that you can apply to all of the charts of this dashboard, in the form of a JSON array of JSON objects. When you apply the overlays, the system displays all the active events that match the specified search term and any specified filter on all the charts in the dashboard. The display uses the color you specify for the overlay and, if selected, vertical lines that mark the event. NOTE: The objects in this array correspond to the suggested event
overlays specified in the web UI, and they're not automatically applied
as active overlays. To set default active event overlays, use the
| |
object (Filters to apply to all the charts of a dashboard) Specifies the properties of filters to apply to the dashboard. Filters give you fine-grained control over the data displayed in the charts in the dashboard. You can specify ad hoc filters or save them as variables for repeated use of the filter criteria. You can also use filters to apply a custom time window to all of the charts in the dashboard. | |
| groupId | string (DashboardGroupId) ID of an existing dashboard group to associate with this dashboard. If you don't specify a value, the system creates a new dashboard group and assigns its ID to this property during the create process. |
| maxDelayOverride | integer <int32> (DashboardMaxDelayOverride) Milliseconds to wait for late-arriving datapoints before rejecting them for inclusion in the charts in this dashboard. This value overrides but doesn't change the max delay setting for individual charts in the dashboard. If you omit this property, the system uses individual chart settings. For individual charts, you can force the system to
calculate a sensible value by removing the chart's |
| name | string (DashboardName) A human-readable label for the dashboard. The web UI displays this label in the dashboard's group. |
Array of objects (DashboardSelectedEventOverlays) List of event overlays that are currently active for the charts in this
dashboard, in the form of a JSON array of JSON objects. For each
overlay, the system displays the active events that match the overlay
search term and optional feature, using the overlay's color and event
line settings. To set options for inactive overlays so you can apply
them at a later time, use the |
Responses
| Content-Type | string Format of the response body. Always "application/json". |
Response Schema: application/json
object (Organizations and teams with write permission for an object) If the write permissions feature is available for your organization, you can use these properties to specify the user and team IDs that have write access to the chart of dashboard. | |
| chartDensity | string (DashboardChartDensity) Default: "DEFAULT" Enum: "DEFAULT" "LOW" "HIGH" "HIGHEST" Controls the number of data points displayed in the charts for this dashboard, over the time span specified for the charts:
|
Array of objects (DashboardCharts) List of charts associated with the dashboard, in the form of a JSON array of JSON objects. Each chart must exist and be unique across all dashboards. | |
| created | integer <int64> (DashboardCreated) The dashboard creation date and time, in the form of a Unix time value The system sets this value, and you can't modify it. |
| creator | string (DashboardCreator) SignalFx-assigned user ID of the user that created the dashboard. If the system created this dashboard, the value is "AAAAAAAAAA". The system sets this value, and you can't modify it. |
| customProperties | object (DashboardCustomProperties) Custom properties for the dashboard, in the form of a JSON object that contains key-value pairs. Custom properties must follow these syntax restrictions: Key:
Value:
|
| description | string (DashboardDescription) Description of the dashboard. The system displays the value in the dashboard tab tooltip in the dashboard group in the web UI. |
| discoveryOptions | object (DashboardDiscoveryOptions) Reserved for system use |
Array of objects (DashboardEventOverlays) List of event overlay definitions that you can apply to all of the charts of this dashboard, in the form of a JSON array of JSON objects. When you apply the overlays, the system displays all the active events that match the specified search term and any specified filter on all the charts in the dashboard. The display uses the color you specify for the overlay and, if selected, vertical lines that mark the event. NOTE: The objects in this array correspond to the suggested event
overlays specified in the web UI, and they're not automatically applied
as active overlays. To set default active event overlays, use the
| |
object (Filters to apply to all the charts of a dashboard) Specifies the properties of filters to apply to the dashboard. Filters give you fine-grained control over the data displayed in the charts in the dashboard. You can specify ad hoc filters or save them as variables for repeated use of the filter criteria. You can also use filters to apply a custom time window to all of the charts in the dashboard. | |
| groupId | string (DashboardGroupId) ID of an existing dashboard group to associate with this dashboard. If you don't specify a value, the system creates a new dashboard group and assigns its ID to this property during the create process. |
| id | string (DashboardId) The dashboard's SignalFx-assigned ID. This value is read-only for a create request. The system assigns it and returns it to you in the response. |
| lastUpdated | integer <int64> (DashboardLastUpdated) The last time the dashboard was updated, in Unix time The system sets this value, and you can't modify it. |
| lastUpdatedBy | string (DashboardLastUpdatedBy) SignalFx-assigned ID of the last user who updated the dashboard. If the last update was by the system, the value is "AAAAAAAAAA". This value is read-only. |
| maxDelayOverride | integer <int32> (DashboardMaxDelayOverride) Milliseconds to wait for late-arriving datapoints before rejecting them for inclusion in the charts in this dashboard. This value overrides but doesn't change the max delay setting for individual charts in the dashboard. If you omit this property, the system uses individual chart settings. For individual charts, you can force the system to
calculate a sensible value by removing the chart's |
| name | string (DashboardName) A human-readable label for the dashboard. The web UI displays this label in the dashboard's group. |
Array of objects (DashboardSelectedEventOverlays) List of event overlays that are currently active for the charts in this
dashboard, in the form of a JSON array of JSON objects. For each
overlay, the system displays the active events that match the overlay
search term and optional feature, using the overlay's color and event
line settings. To set options for inactive overlays so you can apply
them at a later time, use the | |
| tags | Array of strings (Dashboard tags) <= 50 items List of dashboard tags, in the form of a JSON array. Reserved for future use. |
| Content-Type | string Format of the response body. Always "application/json". |
Response Schema: application/json
| code | integer <int32> HTTP response code. Always '400' |
| message | string Error explanation |
Request samples
- Payload
{- "aut