View all methods

snapshots.workflowScores

Return the score for each workflow of a snapshot for the given filters provided. If no filters are applied, it provides it for the organization.

Each workflow has its own response options and unit, so this method returns separate results instead of aggregating scores across workflows.

Facts


Method	`GET https://api.getdx.com/snapshots.workflowScores`
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 results.
`group_ids`	`Array<Text>`	Comma-separated group IDs that limit the results.
`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 workflow scores for one team and its snapshot team, limited to the selected user group, branch, and attribute values:

curl -X GET 'https://api.getdx.com/snapshots.workflowScores?snapshot_id=MjUyNbaY&team_ids=NTA1ODg&snapshot_team_ids=NTIzMTM&group_ids=MzAx&attribute_ids=NDAx,NDAy,NTAx&branch_ids=MjAx' \
  -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
    },
    "teams": [
      {
        "id": "NTA1ODg",
        "name": "Integrations"
      }
    ],
    "snapshot_teams": [
      {
        "id": "NTIzMTM",
        "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": [
    {
      "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
        }
      },
      "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
    },
    {
      "workflow": {
        "id": "NDg3",
        "name": "Focus time",
        "prompt": "How many hours of focus time do you get in a typical day?",
        "options": [
          {
            "label": "Less than 1 hour",
            "value": 0.5
          },
          {
            "label": "1–2 hours",
            "value": 1.5
          },
          {
            "label": "3–4 hours",
            "value": 3.5
          },
          {
            "label": "5–6 hours",
            "value": 5.5
          },
          {
            "label": "More than 6 hours",
            "value": 7
          }
        ],
        "unit": "hours per day",
        "lower_is_better": false,
        "benchmark": {
          "name": "All companies",
          "p_50": 3.2,
          "p_75": 4.4,
          "p_90": 5.1,
          "year": 2026
        }
      },
      "score": 4,
      "distribution": [
        {
          "label": "Less than 1 hour",
          "value": 0.5,
          "count": 0
        },
        {
          "label": "1–2 hours",
          "value": 1.5,
          "count": 1
        },
        {
          "label": "3–4 hours",
          "value": 3.5,
          "count": 1
        },
        {
          "label": "5–6 hours",
          "value": 5.5,
          "count": 2
        },
        {
          "label": "More than 6 hours",
          "value": 7,
          "count": 0
        }
      ],
      "total_respondents": 4,
      "total_cohort": 4,
      "hidden": false
    }
  ]
}

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

Response fields

Response object

Field	Type	Description
`filters`	`Object`	The filter values applied to the request.
`results`	`Array`	One workflow-score result for each workflow.

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.

Workflow score result object

Field	Type	Description
`workflow`	`Object`	The Snapshot Workflow.
`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 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).

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