SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Dashboard Groups API

Dashboard groups let you collect dashboards with common characteristics in one place in the web UI, so you can view them together or in sequence.

The Dashboard Groups API lets you do the following:

  • Create a new dashboard group: POST /dashboardgroup
  • Retrieve the properties of one or more dashboard groups, using a query encoded on the endpoint URL: GET /dashboardgroup
  • Retrieve the properties of a single dashboard group specified by its ID: GET /dashboardgroup/{id}
  • Update the properties of a single dashboard group specified in the {id} path parameter: PUT /dashboardgroup/{id}
  • Make a deep copy (clone) of the dashboard specified in the request body to the group specified in the {id} path parameter: POST `dashboardgroup/{id}/dashboard
  • Add a mirrored dashboard to a group: PUT /dashboardgroup/{id}
  • Delete the dashboard group specified in the {id} path parameter: DELETE /dashboardgroup/{id}

Dashboard groups have options and functionality that depend on the availability of the mirrored dashboard feature in your organization. Read the Developer Guide topic Working with Dashboards before using the Dashboard Groups API

If the write permissions feature is available in your organization, you need to ensure you have write permissions for the following dashboard group operations:

  • Adding dashboards to the group, including mirrored dashboards
  • Rearranging the tab order of the group's dashboards in the web UI
  • Renaming or deleting the group
  • DEPRECATED: Managing links between the group and teams

To make changes to a dashboard in the group or charts in a group's dashboard, you need write permission for the dashboard.

To learn more, see the topic Setting Write Permissions in the product documentation.

Retrieve Dashboard Groups Using Query

Retrieves dashboard groups based on search criteria

Retrieves the properties of one or more dashboard groups, based on search criteria you specify in the endpoint URL. If you don't specify any parameters, you receive the first 50 groups to which the user associated with the auth token has access. Endpoint parameters also control the point in the result set at which the system starts returning groups, and the number of groups to return.

query Parameters
limit
integer <int32>

The maximum number of dashboard groups to return from the overall result set. If the value isn't valid, the system defaults to 50 groups.

name
string

Search string that SignalFx compares to existing dashboard group names. A match occurs if the string matches any part of the name. For example, the query specification name="per" matches the following (ellipses represent other parts of the name):

  • "...dropped per day..."
  • "...95th percentile"
  • "personal disk usage..."

If you specify name="", the system ignores the search string.

The string can only contain ASCII characters.

offset
integer <int32>

0-based index of the point in the overall result set where SignalFx starts returning dashboard groups. If the offset value is greater than the size of the query results, 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

Response Headers
Content-Type
string

Format of the response body. Always "application/json".

Response Schema: application/json
count
integer <int32> (Number of matching dashboard groups)

Success

NOTE: If the request is well-formed but SignalFx can't find any matching dashboard groups, the API still returns 200. In this case, the count property is set to 0, and the results array is empty.

Array of objects

List of dashboard groups, in the form of a JSON array of JSON objects

The size of results and the value of count are not necessarily equal:

  • If you don't specify limit or offset: If count > 50, then sizeOf(results) = 50; otherwise sizeOf(results) = count.
  • If you only specify limit: If count > limit then sizeOf(results) = limit; otherwise sizeOf(results) = count.
  • If you specify limit and offset: If count > (offset + limit) then sizeOf(results) = limit; otherwise, sizeOf(results) = limit.

Response samples

Content type
application/json
{
  • "count": 0,
  • "results":
    [
    ]
}

Create Single Dashboard Group

Creates a dashboard group

Creates a dashboard group using the properties specified in the request body. If your organization has the write permissions feature enabled, you can use the authorizedWriters property to specify the users and teams who have permission to edit or delete the group or its dashboards.

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

Properties that specify a new dashboard group

If you don't specify dashboards to include in this new group, the system creates a new dashboard and assigns it to this group.

object (Organizations and teams with write permission for an object)

Set of organizations and teams that have write permission for the dashboard group, in the form of a JSON object. If your organization has the write permissions feature enabled, you can use this object to specify the user and team IDs that have write access to the dashboard group

Array of objects (List of dashboard configurations)

List of dashboard configurations associated with the dashboard group, in the form of a JSON array of JSON objects. In the web UI, SignalFx uses the set of configurations for a group to determine which dashboards to display for the group.

dashboards
Array of strings (List of dashboards to add to the dashboard group)

List of dashboards, in the form of a JSON array of dashboard IDs. The system adds the specified dashboards to the dashboard group you're creating. If you omit the property, the system creates a new dashboard and assigns it to the new dashboard group.

description
string <UTF-8> (DashboardgroupDescription) <= 1024 characters

Description of the dashboard group. This value appears in the tooltip for the dashboard group on the Dashboards page in the web UI. For this value, you can use up to 1024 UTF-8 characters.

name
required
string (DashboardgroupName) non-empty

Name of the dashboard group. This value identifies the dashboard group in the web UI. It appears on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever you're viewing a dashboard that the group contains.

teams
Array of strings (DashboardgroupTeams)
Deprecated

DEPRECATED: Use the Teams API endpoint /v2/team/{teamId}/dashboardgroup/{dashboardGroupId} to manage links between an existing team and an existing dashboard group. Use the POST method to create a link and the DELETE method to delete a link.
List of existing teams, in the form of a JSON array of team IDs. The dashboard group appears on the team landing page for any team in the list.

Responses

Response Headers
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)

Set of organizations and teams that have write permission for the dashboard group, in the form of a JSON object. If your organization has the write permissions feature enabled, you can use this object to specify the user and team IDs that have write access to the dashboard group

created
integer <int64> (DashboardgroupCreated)

The dashboard group 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 (DashboardgroupCreator)

SignalFx-assigned user ID of the user that created the dashboard group. If the system created this dashboard group, the value is "AAAAAAAAAA". The system sets this value, and you can't modify it.

Array of objects (List of dashboard configurations)

List of dashboard configurations associated with the dashboard group, in the form of a JSON array of JSON objects. In the web UI, SignalFx uses the set of configurations for a group to determine which dashboards to display for the group.

dashboards
Array of strings (List of dashboards to add to the dashboard group)

List of dashboards, in the form of a JSON array of dashboard IDs. The system adds the specified dashboards to the dashboard group you're creating. If you omit the property, the system creates a new dashboard and assigns it to the new dashboard group.

description
string <UTF-8> (DashboardgroupDescription) <= 1024 characters

Description of the dashboard group. This value appears in the tooltip for the dashboard group on the Dashboards page in the web UI. For this value, you can use up to 1024 UTF-8 characters.

id
string (DashboardgroupId)

SignalFx-assigned ID for this dashboard group.

lastUpdated
integer <int64> (DashboardgroupLastUpdated)

The last time the dashboard group was updated, in Unix time

The system sets this value, and you can't modify it.

lastUpdatedBy
string (DashboardgroupLastUpdatedBy)

SignalFx-assigned ID of the last user who updated the dashboard group. If the last update was by the system, the value is "AAAAAAAAAA". This value is "read-only".

name
string (DashboardgroupName) non-empty

Name of the dashboard group. This value identifies the dashboard group in the web UI. It appears on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever you're viewing a dashboard that the group contains.

teams
Array of strings (DashboardgroupTeams)
Deprecated

DEPRECATED: Use the Teams API endpoint /v2/team/{teamId}/dashboardgroup/{dashboardGroupId} to manage links between an existing team and an existing dashboard group. Use the POST method to create a link and the DELETE method to delete a link.
List of existing teams, in the form of a JSON array of team IDs. The dashboard group appears on the team landing page for any team in the list.

Response Headers
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

Content type
application/json
{
  • "authorizedWriters":
    {
    },
  • "dashboardConfigs":
    [
    ],
  • "dashboards":
    [
    ],
  • "description": "string",
  • "name": "string",
  • "teams":
    [
    ]
}

Response samples

Content type
application/json
{
  • "authorizedWriters":
    {
    },
  • "created": 0,
  • "creator": "string",
  • "dashboardConfigs":
    [
    ],
  • "dashboards":
    [
    ],
  • "description": "string",
  • "id": "string",
  • "lastUpdated": 0,
  • "lastUpdatedBy": "string",
  • "name": "string",
  • "teams":
    [
    ]
}

Delete Single Dashboard Group

Deletes a dashboard group

Deletes the dashboard group specified by the {id} path parameter. Dashboards associated with the group are affected as follows:

  • If the mirrored dashboard feature isn't available in your organization: Deleting the dashboard group deletes all the dashboards associated with the group.
  • If the mirrored dashboard feature is available in your organization: If dashboards in the group are mirrored in other groups, then deleting the dashboard group doesn't delete the dashboards. If dashboards in the group aren't mirrored in other groups, then deleting the dashboard group deletes the dashboards.
path Parameters
id
required
string

The SignalFx-assigned ID of an existing dashboard group.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is application/json.

X-SF-TOKEN
required
string

Authentication token

Responses

Response Headers
Content-Type
string
Default: