snapshots.workflowScores.breakdown

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

Facts


Method	`GET https://api.getdx.com/snapshots.workflowScores.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.
`workflow_id`	`Text`	The ID of exactly one workflow 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 workflow’s scores by snapshot team, limited to the selected branch, user group, and attribute values:

curl -X GET 'https://api.getdx.com/snapshots.workflowScores.breakdown?snapshot_id=MjUyNbaY&workflow_id=NDg2&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
    },
    "workflow": {
      "id": "NDg2",
      "name": "Interruption frequency",
      "prompt": "On average, how often are you interrupted at work?",
      "options": [
        {
          "label": "Less than once per day",
          "value": 0.5
        },
        {
          "label": "1–3 times per day",
          "value": 2
        },
        {
          "label": "4–6 times per day",
          "value": 5
        },
        {
          "label": "7–10 times per day",
          "value": 8.5
        },
        {
          "label": "More than 10 times per day",
          "value": 12.5
        }
      ],
      "unit": "per day",
      "lower_is_better": true,
      "benchmark": {
        "name": "All companies",
        "p_50": 4.2,
        "p_75": 3.1,
        "p_90": 2.4,
        "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": 1.25,
      "distribution": [
        {
          "label": "Less than once per day",
          "value": 0.5,
          "count": 2
        },
        {
          "label": "1–3 times per day",
          "value": 2,
          "count": 2
        },
        {
          "label": "4–6 times per day",
          "value": 5,
          "count": 0
        },
        {
          "label": "7–10 times per day",
          "value": 8.5,
          "count": 0
        },
        {
          "label": "More than 10 times per day",
          "value": 12.5,
          "count": 0
        }
      ],
      "total_respondents": 4,
      "total_cohort": 4,
      "hidden": false
    },
    {
      "dimension": {
        "type": "snapshotTeam",
        "id": "NTI5Njc",
        "name": "Analytics"
      },
      "score": null,
      "distribution": null,
      "total_respondents": 2,
      "total_cohort": 2,
      "hidden": true
    }
  ]
}

The visible result’s distribution calculates its score: (0.5 × 2 + 2 × 2) / 4 = 1.25.

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.workflowScores.breakdown?snapshot_id=MjUyNbaY&workflow_id=NDg2&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
    },
    "workflow": {
      "id": "NDg2",
      "name": "Interruption frequency",
      "prompt": "On average, how often are you interrupted at work?",
      "options": [
        {
          "label": "Less than once per day",
          "value": 0.5
        },
        {
          "label": "1–3 times per day",
          "value": 2
        },
        {
          "label": "4–6 times per day",
          "value": 5
        },
        {
          "label": "7–10 times per day",
          "value": 8.5
        },
        {
          "label": "More than 10 times per day",
          "value": 12.5
        }
      ],
      "unit": "per day",
      "lower_is_better": true,
      "benchmark": {
        "name": "All companies",
        "p_50": 4.2,
        "p_75": 3.1,
        "p_90": 2.4,
        "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": 1.25,
      "distribution": [
        {
          "label": "Less than once per day",
          "value": 0.5,
          "count": 2
        },
        {
          "label": "1–3 times per day",
          "value": 2,
          "count": 2
        },
        {
          "label": "4–6 times per day",
          "value": 5,
          "count": 0
        },
        {
          "label": "7–10 times per day",
          "value": 8.5,
          "count": 0
        },
        {
          "label": "More than 10 times per day",
          "value": 12.5,
          "count": 0
        }
      ],
      "total_respondents": 4,
      "total_cohort": 4,
      "hidden": false
    },
    {
      "dimension": {
        "type": "attribute",
        "id": "NDAy",
        "name": "Northeast"
      },
      "score": null,
      "distribution": null,
      "total_respondents": 2,
      "total_cohort": 2,
      "hidden": true
    }
  ]
}

Response fields

Response object

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

Filters object

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

Workflow score result object

Field	Type	Description
`dimension`	`Object`	The dimension represented by this row.
`score`	`Number` or `null`	Weighted average of the distribution values. `null` when hidden.
`distribution`	`Array` or `null`	Counts for each workflow option. `null` when `hidden` is `true`.
`total_respondents`	`Integer`	Respondents who answered the selected workflow.
`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 below 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.

Benchmark object

Benchmark scores use the workflow’s unit. Percentiles represent performance: when workflow.lower_is_better is true, better performance corresponds to a lower score, so P75 and P90 can be lower than P50. When lower_is_better is false, higher scores represent better performance.

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 item object

Field	Type	Description
`label`	`String`	Workflow-option label.
`value`	`Number`	Value assigned to the workflow option.
`count`	`Integer`	Number of respondents who selected the option.

The score is the weighted average of the distribution: sum(value × count) / total_respondents. Distribution counts add up to total_respondents.

DX samples workflow questions, so total_respondents can be less than total_cohort. The cohort counts people who took the survey, not only people who answered this workflow.

When total_cohort is below the account’s minimum threshold (typically 3), hidden is true. With a threshold of 3, a cohort of 2 is hidden and a cohort of 3 is visible. When hidden, score and distribution are null; filters.workflow.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, workflow, dimension, or attribute group does not exist for the current account.