[Dashboard REST API] Properly Use "Group By" Clause

  • 14 June 2021
  • 3 replies


Hello Amplitude,

I’m trying to get data via the Dashboard REST API and was able to successfully pull data via the event segmentation endpoint with an event_type and filters. However, for my next chart I need to use a group_by and I’m struggling to properly format the request for my query. Can someone please provide some guidance on how to properly structure complex queries?

For reference, I’m quite confused by the documentation, since it appears there are three different areas where a group_by can be specified.

The first place it mentions is as a parameter next to the event itself:


The second place is as a parameter within the full event:


The third place is as a parameter within the event segmentation section:



Best answer by Saish Redkar 14 June 2021, 20:23

View original

3 replies

Userlevel 7
Badge +10

Hey @pattsao 
From what I understand, the event segmentation chart end point takes in the following parameters depending on where you want to apply the group by :

  • If you want to apply the group by on the actual event ( similar to using group by in the Events Module ) , then you should be including that as part of the event parameter as a key as the documentation mentions ( second place ). Here you can specify either a user property or an event property on that specific event by using type either as “event” or “user”
    • {
      "event_type": "CompletedProfile",
      "filters": [
      "subprop_type": "event",
      "subprop_key": "EmailVerified",
      "subprop_op": "is",
      "subprop_value": ["true"]
      "group_by": [
      "type": "user"


  • If you want to apply the group by across all users ( similar to applying group by in the Segmentation Module) , then you should be including it as a parameter within the event segmentation ( third place ). Here you can input only a valid user property.

I normally create dictionaries in Python to format these requests. Let me know if you need further help with this.


Hope this helps!


Userlevel 3
Badge +5

Hello @pattsao! Thanks for your question. Happy to help.


To pull event data via the Dashboard REST API you would first want to navigate to the section of the documentation which references your desired endpoint. You can do so by clicking the name of the desired endpoint in the Table of Contents list on the right-hand side of the page:


Within the section for your desired endpoint there will be parameters for how to pull data with a group_by applied. For example, if you wanted to send a request to pull data with a group_by for the Event Segmentation end point the parameters are as follows:


There are also example requests contained within the section pertaining to your desired endpoint:


For example, the proper format for your request using the Event Segmentation endpoint should be formatted like so, 

curl -u API_Key:Secret_Key '\{"event_type":"Event%20Name","filters":\[\{"subprop_type":"type","subprop_key":"property","subprop_op":"is","subprop_value":\["NONE"\]\}\]\}&m=metric&start=YYYYMMDD&end=YYYYMMDD&i=1&g=property'


I hope this is helpful! Let us know if you have questions.


Thanks for the response! It was helpful to think of each part of the query as corresponding to different parts of the Amplitude UI. Really appreciate the help!