View all methods

snapshots.workflowScores.breakdown

Get workflow scores for a completed snapshot by team, group, branch, or attribute.

This method breaks down one workflow.

Facts

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

Arguments

Required arguments

Optional arguments

Filtering behavior

With no population filters, results cover the organization. Values within a filter are combined with OR; different filter types are combined with AND. When both team_ids and snapshot_team_ids are supplied, the selected subtrees are intersected. Disjoint selections match no people.

Attribute values are combined with OR within each attribute group and AND across groups. For example, two Location values and one Role value match people in either location who also have the selected role.

The response includes only the selected filter values. filters.snapshot.completed_count and total_count describe the filtered population, not the whole snapshot. total_count includes eligible recipients and people who completed the snapshot even if excluded from the recipient list.

Breakdown behavior

For snapshotTeam, the default rows are the snapshot’s root teams, with descendants rolled up. If there is a single root team with children, the default rows are its children. Set parent_snapshot_team_id to drill into a team’s direct children. Population filters continue to apply within each row.

For attribute, set attribute_group_id to the category to break down, such as Location. attribute_ids filters the population; it does not choose the breakdown category. Group rows represent user groups. People can belong to more than one group, so row counts are not necessarily additive.

Example request

curl -X GET 'https://api.getdx.com/snapshots.workflowScores.breakdown?snapshot_id=MjUyNbaY&workflow_id=NDg2&dimension_type=snapshotTeam' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx'

Example response

This example uses an account minimum response threshold of 3.

{
  "ok": true,
  "filters": {
    "snapshot": {
      "id": "MjUyNbaY",
      "scheduled_for": "2026-08-02",
      "completed_at": "2026-08-16T14:00:00.000Z",
      "completed_count": 4,
      "total_count": 6
    },
    "teams": [],
    "snapshot_teams": [],
    "groups": [],
    "branches": [],
    "attribute_groups": [],
    "dimension_type": "snapshotTeam",
    "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": null
    }
  },
  "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
    }
  ]
}

Response fields

Field	Type	Description
ok	Boolean	Whether the request succeeded.
filters	Object	The snapshot, applied population filters, and any breakdown selection.
results	Array<Object>	Results for the requested population.

Filters object

Field	Type	Description
snapshot	Object	id, scheduled_for (YYYY-MM-DD), completed_at (ISO 8601), completed_count, and total_count. Counts reflect the applied population filters.
teams	Array<Object>	Selected teams, each with id and name; empty when not filtered.
snapshot_teams	Array<Object>	Selected snapshot teams, each with id and name; empty when not filtered.
groups	Array<Object>	Selected user groups, each with id and name; empty when not filtered.
branches	Array<Object>	Selected branches, each with id and name; empty when not filtered.
attribute_groups	Array<Object>	Groups represented in attribute_ids. Each has id, name, type, and attributes containing only the selected values (id and name). See management types.

The filters also include dimension_type and workflow (the selected item’s metadata). attribute_group (id, name, type) is included for attribute breakdowns; parent_snapshot_team (id, name) is included when a parent is selected.

Result object

Field	Type	Description
dimension	Object	The row identity: type, id, and name.
score	Number or null	Average option value in the workflow’s unit, rounded to four decimal places. null when hidden.
distribution	Array<Object> or null	Each option’s label, numeric value, and response count. N/A is excluded. null when hidden.
total_respondents	Integer	Number of non-N/A workflow answers represented by the row.
total_cohort	Integer	Population count used for the privacy threshold; see below.
hidden	Boolean	Whether the result is suppressed by the account’s minimum response threshold.

Workflow object

See Snapshot Workflow for id, name, prompt, options, unit, lower_is_better, and benchmark. Options use the response scale saved with the snapshot.

Benchmark object

benchmark is null when no benchmark is available. Otherwise, it contains name, p_50, p_75, p_90, and year. DX uses the account’s selected benchmark segment, or the default segment when none is selected.

Privacy and missing data

A result is hidden when total_cohort is below the account’s minimum response threshold. When hidden, score and distribution are null; metadata and counts remain available. For team rows, total_cohort is the completed-response count narrowed by branch, and is not necessarily narrowed by the other population filters. For attribute rows, it counts all users with that attribute value. Group and branch rows use their completed-response counts. Rows without answers in the filtered population are omitted.

Errors

Check ok in every response. When it is false, read error and any error_details.

Field	HTTP status	Description
not_authed	401	The authentication token is missing or invalid.
not_authorized	403	The token does not have access to this method, including the required snapshots:read scope.
invalid_arguments	400	A required argument is missing or a filter or breakdown argument is invalid. error_details identifies the argument.
not_found	404	The snapshot is unknown, belongs to another account, is deleted, or is not completed. The selected workflow may also be unavailable. A malformed workflow_id also returns not_found.