snapshots.sentimentScores.breakdown

Return sentiment scores for one driver in a snapshot, broken down by snapshot team, group, branch, or attribute value.

Facts


Method	`GET https://api.getdx.com/snapshots.sentimentScores.breakdown`
Required scope	`snapshots:read`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`snapshot_id`	`Text`	The unique ID of the snapshot to query.
`driver_id`	`Text`	The ID of exactly one driver in the selected snapshot.
`dimension_type`	`Text`	Breakdown dimension type: `snapshotTeam`, `group`, `branch`, or `attribute`.

Conditionally required arguments

Name	Type	Description
`attribute_group_id`	`Text`	Required when `dimension_type` is `attribute`. The ID of the attribute group whose values define the returned rows.

Optional arguments

Name	Type	Description
`branch_ids`	`Array<Text>`	Comma-separated branch IDs that limit the population.
`group_ids`	`Array<Text>`	Comma-separated group IDs that limit the population.
`team_ids`	`Array<Text>`	Comma-separated Team IDs. Team IDs are consistent across snapshots.
`snapshot_team_ids`	`Array<Text>`	Comma-separated Snapshot Team IDs. Each ID must belong to the selected snapshot.
`attribute_ids`	`Array<Text>`	Comma-separated attribute value IDs. A person must match one selected value from each attribute group represented in this filter.

Filtering behavior

A person must match every supplied filter type provided. With the exception of attributes, the user needs to only meet one of the array-based values provided.

Attribute filters apply per attribute group. A person has at most one attribute value per group. When you provide multiple values from the same group, the person can match any one of those values. When you provide values from multiple groups, the person must match one selected value from every group.

For example, selecting Location values US-East and Northeast, plus the Role value Backend engineer, matches people whose location is US-East or Northeast and whose role is Backend engineer.

The request accepts attribute value IDs in attribute_ids. The response groups the selected values under filters.attribute_groups[].attributes; it includes only selected values, not every value in the group.

Example request

This request returns one driver’s scores by snapshot team, limited to the selected branch, user group, and attribute values:

curl -X GET 'https://api.getdx.com/snapshots.sentimentScores.breakdown?snapshot_id=MjUyNbaY&driver_id=MTQ2&dimension_type=snapshotTeam&branch_ids=MjAx&group_ids=MzAx&attribute_ids=NDAx,NDAy,NTAx' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx'

Example response

This example uses an account minimum threshold of 3:

{
  "ok": true,
  "filters": {
    "snapshot": {
      "id": "MjUyNbaY",
      "scheduled_for": "2026-08-02",
      "completed_at": "2026-08-16T14:00:00.000Z",
      "completed_count": 36,
      "total_count": 40
    },
    "driver": {
      "id": "MTQ2",
      "name": "Ease of release",
      "prompt": "It is easy to release changes to production.",
      "target_role": "dev",
      "benchmark": {
        "name": "All companies",
        "p_50": 58,
        "p_75": 71,
        "p_90": 83,
        "year": 2026
      }
    },
    "dimension_type": "snapshotTeam",
    "teams": [],
    "snapshot_teams": [],
    "branches": [
      {
        "id": "MjAx",
        "name": "Engineering"
      }
    ],
    "groups": [
      {
        "id": "MzAx",
        "name": "Platform"
      }
    ],
    "attribute_groups": [
      {
        "id": "MTAx",
        "name": "Location",
        "type": "admin_managed",
        "attributes": [
          {
            "id": "NDAx",
            "name": "US-East"
          },
          {
            "id": "NDAy",
            "name": "Northeast"
          }
        ]
      },
      {
        "id": "MTAy",
        "name": "Role",
        "type": "self_reported",
        "attributes": [
          {
            "id": "NTAx",
            "name": "Backend engineer"
          }
        ]
      }
    ]
  },
  "results": [
    {
      "dimension": {
        "type": "snapshotTeam",
        "id": "NTIzMTM",
        "name": "Integrations"
      },
      "score": 50,
      "distribution": {
        "very_dissatisfied_count": 0,
        "dissatisfied_count": 0,
        "neutral_count": 2,
        "satisfied_count": 2,
        "very_satisfied_count": 0,
        "idk_na_count": 0
      },
      "total_votes": 2,
      "total_respondents": 4,
      "total_cohort": 4,
      "hidden": false
    },
    {
      "dimension": {
        "type": "snapshotTeam",
        "id": "NTI5Njc",
        "name": "Analytics"
      },
      "score": null,
      "distribution": null,
      "total_votes": 1,
      "total_respondents": 2,
      "total_cohort": 3,
      "hidden": true
    }
  ]
}

Attribute breakdown example

This request breaks down results by Location. It filters to people whose location is US-East or Northeast and whose role is Backend engineer:

curl -X GET 'https://api.getdx.com/snapshots.sentimentScores.breakdown?snapshot_id=MjUyNbaY&driver_id=MTQ2&dimension_type=attribute&attribute_group_id=MTAx&attribute_ids=NDAx,NDAy,NTAx' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx'

The response identifies the selected AttributeGroup separately from each attribute value. This example uses an account minimum threshold of 3:

{
  "ok": true,
  "filters": {
    "snapshot": {
      "id": "MjUyNbaY",
      "scheduled_for": "2026-08-02",
      "completed_at": "2026-08-16T14:00:00.000Z",
      "completed_count": 36,
      "total_count": 40
    },
    "driver": {
      "id": "MTQ2",
      "name": "Ease of release",
      "prompt": "It is easy to release changes to production.",
      "target_role": "dev",
      "benchmark": {
        "name": "All companies",
        "p_50": 58,
        "p_75": 71,
        "p_90": 83,
        "year": 2026
      }
    },
    "dimension_type": "attribute",
    "teams": [],
    "snapshot_teams": [],
    "attribute_group": {
      "id": "MTAx",
      "name": "Location",
      "type": "admin_managed"
    },
    "branches": [],
    "groups": [],
    "attribute_groups": [
      {
        "id": "MTAx",
        "name": "Location",
        "type": "admin_managed",
        "attributes": [
          {
            "id": "NDAx",
            "name": "US-East"
          },
          {
            "id": "NDAy",
            "name": "Northeast"
          }
        ]
      },
      {
        "id": "MTAy",
        "name": "Role",
        "type": "self_reported",
        "attributes": [
          {
            "id": "NTAx",
            "name": "Backend engineer"
          }
        ]
      }
    ]
  },
  "results": [
    {
      "dimension": {
        "type": "attribute",
        "id": "NDAx",
        "name": "US-East"
      },
      "score": 50,
      "distribution": {
        "very_dissatisfied_count": 0,
        "dissatisfied_count": 0,
        "neutral_count": 1,
        "satisfied_count": 1,
        "very_satisfied_count": 0,
        "idk_na_count": 0
      },
      "total_votes": 2,
      "total_respondents": 2,
      "total_cohort": 2,
      "hidden": false
    },
    {
      "dimension": {
        "type": "attribute",
        "id": "NDAy",
        "name": "Northeast"
      },
      "score": null,
      "distribution": null,
      "total_votes": 3,
      "total_respondents": 3,
      "total_cohort": 3,
      "hidden": true
    }
  ]
}

Response fields

Response object

Field	Type	Description
`filters`	`Object`	Resolved filters applied to the request.
`results`	`Array`	One sentiment-score result for each returned dimension.

Filters object

Field	Type	Description
`snapshot`	`Object`	The selected snapshot and its scheduling and completion metadata.
`driver`	`Object`	The selected driver.
`dimension_type`	`String`	The requested breakdown dimension type.
`attribute_group`	`Object`	The attribute group that defines the breakdown rows. Returned only when `dimension_type` is `attribute`; distinct from `attribute_groups`, which describes applied attribute filters.
`branches`	`Array<Object>`	Applied branch filters, each with an `id` and `name`.
`groups`	`Array<Object>`	Applied user group filters, each with an `id` and `name`.
`teams`	`Array<Object>`	Applied team filters, each with an `id` and `name`.
`snapshot_teams`	`Array<Object>`	Applied snapshot team filters, each with an `id` and `name`.
`attribute_groups`	`Array<Object>`	Attribute groups represented in the applied filter, each containing only its selected attribute values.

Snapshot filter object

filters.snapshot describes the selected snapshot. Its completion counts describe the whole snapshot, before applying population filters.

Field	Type	Description
`id`	`String`	The snapshot ID.
`scheduled_for`	`String`	Scheduled survey date in `YYYY-MM-DD` format.
`completed_at`	`String` or `null`	Timestamp when the snapshot completed, in ISO 8601 format. `null` if it has not completed.
`completed_count`	`Integer`	Number of people who completed the snapshot.
`total_count`	`Integer`	Total number of people in the snapshot cohort.

Attribute group filter object

Each item in filters.attribute_groups contains an attribute group’s identity and the attribute values selected in the filter.

Field	Type	Description
`id`	`String`	The attribute-group ID.
`name`	`String`	The attribute-group name.
`type`	`String`	Management type: `admin_managed`, `self_reported`, or `dx_managed`.
`attributes`	`Array<Object>`	Selected attribute values belonging to this group. A person must match one of these values to satisfy this group’s filter.

Field	Type	Description
`id`	`String`	The selected attribute value ID.
`name`	`String`	The selected attribute value name.

Group, branch, and team filter reference object

Each item in filters.groups, filters.branches, filters.teams, and filters.snapshot_teams identifies a selected filter value.

Field	Type	Description
`id`	`String`	The selected group’s, branch’s, team’s, or snapshot team’s ID.
`name`	`String`	The selected group’s, branch’s, team’s, or snapshot team’s name.

Sentiment score result object

Field	Type	Description
`dimension`	`Object`	The dimension represented by this row.
`score`	`Number` or `null`	Percentage of favorable ratings. `null` when `hidden` is `true`.
`distribution`	`Object` or `null`	Counts of selected ratings. `null` when `hidden` is `true`.
`total_votes`	`Integer`	Number of respondents who marked the selected driver as important.
`total_respondents`	`Integer`	Respondents who answered the selected driver.
`total_cohort`	`Integer`	People who took the survey in the filtered population for this result, whether or not they answered this question.
`hidden`	`Boolean`	`true` when `total_cohort` is at least the account’s minimum threshold (typically 3).

Dimension object

Field	Type	Description
`type`	`String`	Dimension type: `snapshotTeam`, `group`, `branch`, or `attribute`.
`id`	`String`	Dimension ID, scoped by `type`.
`name`	`String`	Dimension name.

Driver object

Field	Type	Description
`id`	`String`	The unique driver ID.
`name`	`String`	The driver name.
`prompt`	`String`	The driver prompt shown to users.
`target_role`	`String`	Who the driver is shown to: `dev`, `nondev`, or `all`.
`benchmark`	`Object`	Workspace-default benchmark for the driver.

Benchmark object

Field	Type	Description
`name`	`String`	The workspace-default benchmark name.
`p_50`	`Number`	50th-percentile benchmark score.
`p_75`	`Number`	75th-percentile benchmark score.
`p_90`	`Number`	90th-percentile benchmark score.
`year`	`Integer`	Year of the benchmark.

Distribution object

Field	Type	Description
`very_dissatisfied_count`	`Integer`	Very dissatisfied ratings.
`dissatisfied_count`	`Integer`	Dissatisfied ratings.
`neutral_count`	`Integer`	Neutral ratings.
`satisfied_count`	`Integer`	Satisfied ratings.
`very_satisfied_count`	`Integer`	Very satisfied ratings.
`idk_na_count`	`Integer`	I don’t know or not applicable ratings.

The score is the percentage of selected ratings that are favorable: satisfied_count plus very_satisfied_count.

When total_cohort is at least the account’s minimum threshold (typically 3), hidden is true. Equality triggers suppression: with a threshold of 3, a cohort of 2 is visible and a cohort of 3 is hidden. When hidden, score and distribution are null; the driver benchmark and count fields remain available.

Errors

Check ok in every response. If it is false, use the error code to identify the problem.

Error	Description
`not_authed`	No authentication token provided.
`invalid_auth`	DX cannot validate the authentication credentials.
`invalid_arguments`	A required argument is missing, or a dimension or filter value is invalid.
`not_found`	The snapshot, driver, dimension, or attribute group does not exist for the current account.