Skip to main content

​
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 typeDefault aggregate_by
STACKED_BAR_METRICBRAND
GRAPH typesCHANNEL 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

{
  "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.