/reports/data response is now structured by aggregate_by and secondary_aggregate_by

Changed

Response grouping for GET https://dashboard.dashsocial.com/reports/data is now controlled by two parameters:

aggregate_by sets the primary grouping dimension. Accepted values:

TOTAL, BRAND, CHANNEL, ACCOUNT_TAG, TAG, SOURCE_CAMPAIGN, AGE_GENDER,
COUNTRY, REGION, PUBLISHER_PLATFORM, FOLLOWER_STATUS, ASSIGNEE, MESSAGE_TAG,
MESSAGE_TYPE, SENTIMENT, TOPIC, MEDIA_TYPE, STATE_PROVINCE, CITY, MENTION_TYPE,
INDUSTRY, AGE, GENDER, CAMPAIGN, BOARD, GALLERY, CONTENT_TAG

secondary_aggregate_by adds an optional second grouping dimension. It is now supported on report_type=TOTAL_METRIC and report_type=GRAPH (previously stacked bars only).

We recommend always including aggregate_by in your request. If it is omitted, the endpoint falls back to a default that depends on the report type and the brands and channels in your request, so the grouping may not be what you want.

Report type	Default `aggregate_by`
`STACKED_BAR_METRIC`	`BRAND`
`GRAPH` types	`CHANNEL` if more than one channel is requested; otherwise `BRAND` if more than one brand is requested; otherwise `TOTAL`
Other types (e.g. `TOTAL_GROUPED_METRIC`)	the first available breakdown, usually `CHANNEL`

What you need to update

Set aggregate_by to the grouping your report needs. For a brand-and-channel breakdown, use aggregate_by=BRAND and secondary_aggregate_by=CHANNEL.
Read metrics from each entry. The path matches your grouping:
- With secondary_aggregate_by: data[<aggregate_by>]["breakdowns"][<secondary_aggregate_by>]["metrics"]["<METRIC>"]["<CHANNEL>"]
- Without it, the breakdowns level is dropped: data[<aggregate_by>]["metrics"]["<METRIC>"]["<CHANNEL>"]
<CHANNEL> is the channel name when the data is split by channel, otherwise ALL_CHANNELS.

Response structure: TOTAL_METRIC

{
  "data": {
    "1": {                               // brand id
      "avatar": "...",
      "data_type": "BRAND",
      "name": "Test Brand",
      "permissions": { ... },
      "user_has_access": true,
      "breakdowns": {                    // metric data lives here
        "FACEBOOK": {
          "data_type": "CHANNEL",
          "name": "Facebook",
          "metrics": {
            "TOTAL_ENGAGEMENTS": { "FACEBOOK": { "value": 3440.0 } },
            "TOTAL_REACH":       { "FACEBOOK": { "value": 130303.0 } }
          }
        },
        "INSTAGRAM": {
          "metrics": {
            "TOTAL_ENGAGEMENTS": { "INSTAGRAM": { "value": 12228.0 } },
            "TOTAL_REACH":       { "INSTAGRAM": { "value": 369475.0 } }
          }
        }
      }
    },
    "2": { ... },                        // another brand, same shape
    "metrics": {
      "TOTAL_ENGAGEMENTS": { "ALL_CHANNELS": { "value": 23178.0 } },
      "TOTAL_REACH":       { "ALL_CHANNELS": { "value": 658241.0 } }
    }
  }
}

For TOTAL_METRIC, the innermost object is a single value.

Response structure: GRAPH

{
  "data": {
    "1": {                               // brand id
      "avatar": "...",
      "data_type": "BRAND",
      "name": "Test Brand",
      "permissions": { ... },
      "user_has_access": true,
      "breakdowns": {                    // metric data lives here
        "FACEBOOK": {
          "data_type": "CHANNEL",
          "name": "Facebook",
          "metrics": {
            "TOTAL_ENGAGEMENTS": { "FACEBOOK": { "2026-05-06": 106.0, "2026-06-01": 1055.0 } },
            "TOTAL_REACH":       { "FACEBOOK": { "2026-05-06": 5359.0, "2026-06-01": 29441.0 } }
          }
        },
        "INSTAGRAM": {
          "metrics": {
            "TOTAL_ENGAGEMENTS": { "INSTAGRAM": { "2026-05-03": 1109.0, "2026-06-03": 11.0 } },
            "TOTAL_REACH":       { "INSTAGRAM": { "2026-05-03": 19631.0, "2026-06-03": 26183.0 } }
          }
        }
      }
    },
    "2": { ... },                        // another brand, same shape
    "metrics": {
      "TOTAL_ENGAGEMENTS": { "ALL_CHANNELS": { "2026-05-03": 1109.0 } },
      "TOTAL_REACH":       { "ALL_CHANNELS": { "2026-05-03": 19631.0 } }
    }
  }
}

For GRAPH, the innermost object is keyed by date.

Notes

A brand only includes a channel under breakdowns if it has data for that channel. In the examples above, brand 2 returns Instagram only. The two report types share the same structure. Only the innermost object differs: date-keyed values for GRAPH, a single value for TOTAL_METRIC.

​Changed

​What you need to update

​Response structure: TOTAL_METRIC

​Response structure: GRAPH

​Notes

Changed

What you need to update

Response structure: TOTAL_METRIC

Response structure: GRAPH

Notes