> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dashsocial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# /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

1. Set `aggregate_by` to the grouping your report needs. For a brand-and-channel breakdown, use `aggregate_by=BRAND` and `secondary_aggregate_by=CHANNEL`.
2. 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

```jsonc theme={null}
{
  "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

```jsonc theme={null}
{
  "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`.