snapshots.sentimentScores

Return one sentiment-score result for each driver in a snapshot. Each result includes its driver object, score, and distribution. You can filter the population by branch, group, team, snapshot team, or attribute value.

Facts


Method	`GET https://api.getdx.com/snapshots.sentimentScores`
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.

Optional arguments

Name	Type	Description
`branch_ids`	`Array<Text>`	Comma-separated branch IDs that limit the aggregate.
`group_ids`	`Array<Text>`	Comma-separated user group IDs that limit the aggregate.
`team_ids`	`Array<Text>`	Comma-separated team IDs. Team IDs will be consistent across snapshots, whereas snapshot team IDs are unique for just that snapshot.
`snapshot_team_ids`	`Array<Text>`	Comma-separated snapshot team IDs.
`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

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

Example response

{
  "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
    },
    "teams": [
      {
        "id": "NTA1ODg",
        "name": "Integrations"
      }
    ],
    "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": [
    {
      "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
        }
      },
      "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
    },
    {
      "driver": {
        "id": "MTQ3",
        "name": "Review turnaround",
        "prompt": "Code reviews are completed in a timely manner.",
        "target_role": "dev",
        "benchmark": {
          "name": "All companies",
          "p_50": 61,
          "p_75": 74,
          "p_90": 86,
          "year": 2026
        }
      },
      "score": 100,
      "distribution": {
        "very_dissatisfied_count": 0,
        "dissatisfied_count": 0,
        "neutral_count": 0,
        "satisfied_count": 2,
        "very_satisfied_count": 2,
        "idk_na_count": 0
      },
      "total_votes": 2,
      "total_respondents": 4,
      "total_cohort": 4,
      "hidden": false
    }
  ]
}

Response fields

Response object

Field	Type	Description
`filters`	`Object`	The filter values applied to the aggregate.
`results`	`Array<Object>`	One sentiment-score result per driver for the filtered population.

Filters object

Field	Type	Description
`snapshot`	`Object`	The selected snapshot and its scheduling and completion metadata.
`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 object

Field	Type	Description
`driver`	`Object`	The driver represented by this result.
`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`. The sum of the distribution items may not equal `total_respondents` depending on the driver’s `target_role`.
`total_votes`	`Integer`	Number of respondents who marked this driver as important.
`total_respondents`	`Integer`	Number of individuals in the cohort who completed the snapshot.
`total_cohort`	`Integer`	Number of individuals in the cohort who could have completed the snapshot.
`hidden`	`Boolean`	`true` when `total_cohort` is at least the account’s minimum threshold (typically 3).

Driver object

Field	Type	Description
`id`	`String`	The driver’s ID.
`name`	`String`	The driver name.
`prompt`	`String`	The driver question shown to respondents.
`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.

Each driver’s score is the percentage of selected ratings that are favorable: satisfied_count plus very_satisfied_count. Values are null when hidden is true.

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 filter value is invalid.
`not_found`	The snapshot does not exist for the current account.