# 查询 API

> 本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。

查询 API 主要用于获取各种数据分析报告。

## 1. 调用方法

请参见 [API 文档](https://54td.gitbook.io/shence/technical_guide/secondary_development/api) 中的调用方法描述。

## 2. 通用参数

### 2.1 属性表达式

几乎所有的 API 都会用到属性表达式，例如按照某个属性进行过滤、分组或者聚合等等。属性包括事件属性和用户属性，事件属性使用 **event.事件名.属性名** 的方式，例如表示 **注册渠道** 这个属性的表达式如下:

```
  event.Signup.Channel
```

用户属性类似，例如表示 **用户性别**:

```
  user.Gender
```

### 2.2 筛选表达式

筛选表达式同样适用于绝大多数 API，用于表示对某些事件或者用户的筛选操作，使用如下格式的 JSON 表示:

```javascript
{
  // 表示 conditions 里的各个条件的关系是 或 还是 且 
  "relation": "and",
  // 具体的条件列表，可以有多个
  "conditions": [{
    // 条件的左值，是一个属性表达式
    "field": "event.BuyGold.$os",
    // 条件的操作符，这里表示等于
    "function": "equal",
    // 条件的参数，根据不同的操作符可以有一个或者多个
    "params": [
      "iOS"
    ]
  }, {
    "field": "user.Gender",
    "function": "equal",
    "params": [
      "男"
    ]
  }]
}
```

目前支持的操作符如下:

* equal / notEqual

  表示等于/不等于，对字符串、数值类型有效。如果 Params 有多个，则相当于 In 或者 Not In。例如想筛选出来自北京或者上海的用户:

  ```javascript
  {
    "field": "user.$city",
    "function": "equal",
    "params": ["北京", "上海"]
  }
  ```
* isTrue / isFalse

  只对布尔类型有效。
* isSet / notSet

  某个属性是否有值，对字符串、数值类型有效。
* include

  针对集合的操作，表示包含某个元素，例如筛选出所有喜欢苹果的用户:

  ```javascript
  {
    "field": "user.FavoriteFruits",
    "function": "include",
    "params": ["Apple"]
  }
  ```
* less / greater / between：表示小于/大于/小于且大于，其中 between 是前闭后闭的区间，只对数值类型有效。例如筛选买入黄金的价格在 230 和 232 之间的所有事件:

  ```javascript
  {
    "field": "event.BuyGold.GoldPrice",
    "function": "between",
    "params": [230, 232]
  }
  ```
* contain / notContain

  包含或者不包含，表示字符串的部分匹配，只对字符串类型有效。
* absoluteBetween / relativeBefore / relativeWithin

  针对日期类型的操作符，分别表示在一个绝对日期范围/在 N 天之前/在 N 天之内。例如想筛选所有注册时间在 3 天之内的用户:

  ```javascript
  {
    "field": "user.$signup_time",
    "function": "relativeWithin",
    "params": [3]
  }
  ```

  或者筛选所有在 2015-1-1\~2015-1-10 注册的用户:

  ```javascript
  {
    "field": "user.$signup_time",
    "function": "absoluteBetween",
    "params": ["2015-01-01", "2015-01-10"]
  }
  ```

## 3. 行为分析报告

所有的分析报告均有 JSON 和 CSV 两种格式，默认是 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析报告对应的 CSV 格式的 URL 为: **/events/report?format=csv** 。

### 3.1 事件分析报告

> \[POST /events/report]

* Request (application/json) 

```javascript
{
    "measures":[
        {
            // 事件名称，特别的，可以使用 $Anything 表示任意事件
            "event_name":"payOrder",
            // 聚合操作符
            "aggregator":"uniq_count",
            //（可选）对于指标的筛选条件
            "filter": {
                "conditions": [
                    {
                        "field": "user.sex", 
                        "function": "equal", 
                        "params": [
                            "男"
                        ]
                    }
                ]
            }
        }
    ],
    // 起始日期
    "from_date":"2018-04-30",
    // 结束日期
    "to_date":"2018-05-02",
    // 时间单位，可以是 hour/day/week/month
    "unit":"day",
    //（可选）筛选条件
    "filter":{
        "relation":"and",
        "conditions":[
            {
                "field":"event.payOrder.$lib_version",
                "function":"equal",
                "params":[
                    "1.6.18"
                ]
            },
            {
                "field":"event.payOrder.$lib",
                "function":"equal",
                "params":[
                    "Android"
                ]
            }
        ]
    },
    //（可选）分组属性，可以有零个或者多个
    "by_fields":[
        "event.payOrder.$screen_width",
        "event.payOrder.$screen_height"
    ],
    //（可选）分桶条件，对数值型属性进行分组时，可以自定义分桶条件
    "bucket_params":{
        "event.payOrder.$screen_width":[2000,3000],
        "event.payOrder.$screen_height":[2000]
    },
    // 是否计算合计值
    "detail_and_rollup":true,
    //（可选）抽样因子，64为全量，32为2分之1抽样
    "sampling_factor":64,
    //（可选）使用近似计算
    "approx":true,
    //（可选）基数计算算法hyperloglog的精度，值越大精度越高，但对应内存占用也会变高，推荐用12。
    "hll_precision":12,
    //（可选）使用近似计算合计，当“approx”为true时，“approx_total”也设为true，当“approx”为false时，如果“approx_total”为true，那合计会以近似计算算法得出
    "approx_total":false,
    //（可选）最大分组个数
    "limit":1000,
    //（可选）使用缓存，若缓存中找不到相应数据，则从数据库读出
    "use_cache":true
}
```

* Response 200 (application/json) 

```javascript
{
    "by_fields":[
        "event.$Anything.$screen_width",
        "event.$Anything.$screen_height"
    ],
    "series":[
        "2018-04-30 00:00:00",
        "2018-05-01 00:00:00",
        "2018-05-02 00:00:00"
    ],
    "rows":[
        {
        "values":[
            [57],
            [60],
            [38]
        ],
        "by_values":[
            "-INF~2000",
            "-INF~2000"
        ]
        },
        {
        "values":[
            [7],
            [7],
            [2]
        ],
        "by_values":[
            "2000~3000",
            "-INF~2000"
        ]
        }
    ],
    "num_rows": 2,
    "total_rows": 2,
    "report_update_time": "2018-05-02 13:51:08.356",
    "data_update_time": "2018-05-02 16:03:32.000",
    "data_sufficient_update_time": "2018-05-02 16:03:32.000",
    "truncated": false
}
```

* 使用 curl 示例 

```bash
curl 'https://golddemo.cloud.sensorsdata.cn/api/events/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '{
    "measures": [
        {
            "event_name": "payOrder", 
            "aggregator": "unique", 
            "filter": {
                "conditions": [
                    {
                        "field": "user.sex", 
                        "function": "equal", 
                        "params": [
                            "男"
                        ]
                    }
                ]
            }
        }
    ], 
    "from_date": "2018-04-30", 
    "to_date": "2018-05-02", 
    "unit": "day", 
    "filter": {
        "relation": "and", 
        "conditions": [
            {
                "field": "event.payOrder.$lib_version", 
                "function": "equal", 
                "params": [
                    "1.6.18"
                ]
            }, 
            {
                "field": "event.payOrder.$lib", 
                "function": "equal", 
                "params": [
                    "Android"
                ]
            }
        ]
    }, 
    "by_fields": [
        "event.payOrder.$screen_width", 
        "event.payOrder.$screen_height"
    ], 
    "bucket_params": {
        "event.payOrder.$screen_width": [
            2000, 
            3000
        ], 
        "event.payOrder.$screen_height": [
            2000
        ]
    }, 
    "unit":"day",
    "detail_and_rollup": true,
    "sampling_factor": 64, 
    "approx": true, 
    "hll_precision": 12, 
    "approx_total": false, 
    "limit": 1000, 
    "use_cache": true
}
'
```

> 关键参数说明：
>
> * **aggregator:** 聚合操作符，可取值为：
>   * count: 事件触发次数
>   * uniq\_count:触发用户数
>   * uniq\_avg:人均次数或人均值
>   * sum: 数值总和
>   * max:数值最大值
>   * min:数值最小值
>   * avg:数值平均值
> * **field:** 若aggregator为sum/max/min/avg，需要添加field字段，即聚合的字段名，与aggregator同级，例如：“field" : "event.payOrder.discountAmount"
> * **bucket\_params:** 分桶条件，对数值型属性进行分组时，可以自定义分桶条件，分桶条件里所包含的属性必须全包含在分组属性“by\_fields”
> * **limit:** 最大分组个数，如果limit较大（超过1W），建议使用stream模式下载（仅对于事件分析）。stream模式开启：添加参数“downloadOriginalFormat” : true

### 3.2 漏斗分析报告

> \[POST /funnels/report]

* Request (application/json) 

```javascript
{
  // 漏斗 ID
  "funnel_id": 158,
  // 起始日期
  "from_date": "2015-04-17",
  // 结束日期
  "to_date": "2015-04-19",
  // 筛选条件
  "filter": {
    "conditions": [
      {
        "field": "event.$Anything.$lib_version",
        "function": "contain",
        "params": [
          "0.1.0"
        ]
      },
      {
        "field": "event.$Anything.$lib",
        "function": "contain",
        "params": [
          "python"
        ]
      },
      {
        "field": "user.Gender",
        "function": "equal",
        "params": [
          "男"
        ]
      }
    ],
    "relation": "and"
  },
  // （可选）分组属性
  "by_field": "event.$Anything.$os",
  // 是否限制漏斗所有步骤在事件窗口内，true:不限制，false:限制
  "extend_over_end_date": true,
  // （可选）事件 & 用户 筛选，分组的步骤id，如果为 -1 表示所有事件
  "by_field_step": -1,
  // （可选）抽样
  "sampling_factor": 64,
  // 标识filter.conditions是针对任意步骤还是某个步骤，如果-1则为任意步骤, 否则填写步骤序号。
  "filter_field_steps": [-1]
}
```

> 在 1.13 及以上的版本中，我们支持 "from\_date" 与 "to\_date" 使用"秒级精度"或"天级精度"进行筛选

示例：

```
// 使用秒级精度
"from_date": "2015-04-17 22:00:00",
"to_date" : "2015-04-18 22:00:00",
```

* 系统将会匹配出时间范围为 2015-04-17 22:00:00.000 至 2015-04-18 22:00:00.999 的全部数据

```
// 使用天级精度
"from_date": "2015-04-17",
"to_date" : "2015-04-18",
```

* 系统将会匹配出时间范围为 2015-04-17 00:00:00.000 至 2015-04-18 23:59:59.999 的全部数据
* Response 200 (application/json) 

```javascript
{
  "date_list": [
    "$ALL",
    "2017-04-17",
    "2017-04-18",
    "2017-04-19"
  ],
  "funnel_detail": [
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 98726,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 76110,
              "conversion_rate": 77.09,
              "wastage_user": 22616,
              "median_converted_time": 1505
            },
            {
              "converted_user": 76110,
              "conversion_rate": 77.09,
              "wastage_user": 22616,
              "median_converted_time": 1505
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 76110,
          "conversion_rate": 77.09,
          "rows": [
            {
              "converted_user": 21266,
              "conversion_rate": 27.94,
              "wastage_user": 54844,
              "median_converted_time": 2530
            },
            {
              "converted_user": 21266,
              "conversion_rate": 27.94,
              "wastage_user": 54844,
              "median_converted_time": 2530
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 21266,
          "conversion_rate": 27.94,
          "rows": [
            {
              "converted_user": 17522,
              "conversion_rate": 82.39,
              "wastage_user": 3744,
              "median_converted_time": 939
            },
            {
              "converted_user": 17522,
              "conversion_rate": 82.39,
              "wastage_user": 3744,
              "median_converted_time": 939
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 17522,
          "conversion_rate": 82.39,
          "rows": []
        }
      ],
      "completion_rate": 17.75,
      "overview": [
        [
          {
            "converted_user": 98726,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 76110,
            "conversion_rate": 77.09,
            "completion_rate": 77.09
          },
          {
            "converted_user": 21266,
            "conversion_rate": 27.94,
            "completion_rate": 21.54
          },
          {
            "converted_user": 17522,
            "conversion_rate": 82.39,
            "completion_rate": 17.75
          }
        ],
        [
          {
            "converted_user": 98726,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 76110,
            "conversion_rate": 77.09,
            "completion_rate": 77.09
          },
          {
            "converted_user": 21266,
            "conversion_rate": 27.94,
            "completion_rate": 21.54
          },
          {
            "converted_user": 17522,
            "conversion_rate": 82.39,
            "completion_rate": 17.75
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 34099,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 26813,
              "conversion_rate": 78.63,
              "wastage_user": 7286,
              "median_converted_time": 1537
            },
            {
              "converted_user": 26813,
              "conversion_rate": 78.63,
              "wastage_user": 7286,
              "median_converted_time": 1537
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 26813,
          "conversion_rate": 78.63,
          "rows": [
            {
              "converted_user": 7787,
              "conversion_rate": 29.04,
              "wastage_user": 19026,
              "median_converted_time": 2710
            },
            {
              "converted_user": 7787,
              "conversion_rate": 29.04,
              "wastage_user": 19026,
              "median_converted_time": 2710
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 7787,
          "conversion_rate": 29.04,
          "rows": [
            {
              "converted_user": 6449,
              "conversion_rate": 82.82,
              "wastage_user": 1338,
              "median_converted_time": 942
            },
            {
              "converted_user": 6449,
              "conversion_rate": 82.82,
              "wastage_user": 1338,
              "median_converted_time": 942
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 6449,
          "conversion_rate": 82.82,
          "rows": []
        }
      ],
      "completion_rate": 18.91,
      "overview": [
        [
          {
            "converted_user": 34099,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26813,
            "conversion_rate": 78.63,
            "completion_rate": 78.63
          },
          {
            "converted_user": 7787,
            "conversion_rate": 29.04,
            "completion_rate": 22.84
          },
          {
            "converted_user": 6449,
            "conversion_rate": 82.82,
            "completion_rate": 18.91
          }
        ],
        [
          {
            "converted_user": 34099,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26813,
            "conversion_rate": 78.63,
            "completion_rate": 78.63
          },
          {
            "converted_user": 7787,
            "conversion_rate": 29.04,
            "completion_rate": 22.84
          },
          {
            "converted_user": 6449,
            "conversion_rate": 82.82,
            "completion_rate": 18.91
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 34445,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 26701,
              "conversion_rate": 77.52,
              "wastage_user": 7744,
              "median_converted_time": 1521
            },
            {
              "converted_user": 26701,
              "conversion_rate": 77.52,
              "wastage_user": 7744,
              "median_converted_time": 1521
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 26701,
          "conversion_rate": 77.52,
          "rows": [
            {
              "converted_user": 7407,
              "conversion_rate": 27.74,
              "wastage_user": 19294,
              "median_converted_time": 2594
            },
            {
              "converted_user": 7407,
              "conversion_rate": 27.74,
              "wastage_user": 19294,
              "median_converted_time": 2594
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 7407,
          "conversion_rate": 27.74,
          "rows": [
            {
              "converted_user": 6111,
              "conversion_rate": 82.5,
              "wastage_user": 1296,
              "median_converted_time": 956
            },
            {
              "converted_user": 6111,
              "conversion_rate": 82.5,
              "wastage_user": 1296,
              "median_converted_time": 956
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 6111,
          "conversion_rate": 82.5,
          "rows": []
        }
      ],
      "completion_rate": 17.74,
      "overview": [
        [
          {
            "converted_user": 34445,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26701,
            "conversion_rate": 77.52,
            "completion_rate": 77.52
          },
          {
            "converted_user": 7407,
            "conversion_rate": 27.74,
            "completion_rate": 21.5
          },
          {
            "converted_user": 6111,
            "conversion_rate": 82.5,
            "completion_rate": 17.74
          }
        ],
        [
          {
            "converted_user": 34445,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 26701,
            "conversion_rate": 77.52,
            "completion_rate": 77.52
          },
          {
            "converted_user": 7407,
            "conversion_rate": 27.74,
            "completion_rate": 21.5
          },
          {
            "converted_user": 6111,
            "conversion_rate": 82.5,
            "completion_rate": 17.74
          }
        ]
      ]
    },
    {
      "steps": [
        {
          "event_name": "ViewHomePage",
          "converted_user": 33579,
          "conversion_rate": 100,
          "rows": [
            {
              "converted_user": 25271,
              "conversion_rate": 75.26,
              "wastage_user": 8308,
              "median_converted_time": 1485
            },
            {
              "converted_user": 25271,
              "conversion_rate": 75.26,
              "wastage_user": 8308,
              "median_converted_time": 1485
            }
          ]
        },
        {
          "event_name": "ViewProduct",
          "converted_user": 25271,
          "conversion_rate": 75.26,
          "rows": [
            {
              "converted_user": 6845,
              "conversion_rate": 27.09,
              "wastage_user": 18426,
              "median_converted_time": 2469
            },
            {
              "converted_user": 6845,
              "conversion_rate": 27.09,
              "wastage_user": 18426,
              "median_converted_time": 2469
            }
          ]
        },
        {
          "event_name": "SubmitOrder",
          "converted_user": 6845,
          "conversion_rate": 27.09,
          "rows": [
            {
              "converted_user": 5599,
              "conversion_rate": 81.8,
              "wastage_user": 1246,
              "median_converted_time": 928
            },
            {
              "converted_user": 5599,
              "conversion_rate": 81.8,
              "wastage_user": 1246,
              "median_converted_time": 928
            }
          ]
        },
        {
          "event_name": "PayOrder",
          "converted_user": 5599,
          "conversion_rate": 81.8,
          "rows": []
        }
      ],
      "completion_rate": 16.67,
      "overview": [
        [
          {
            "converted_user": 33579,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 25271,
            "conversion_rate": 75.26,
            "completion_rate": 75.26
          },
          {
            "converted_user": 6845,
            "conversion_rate": 27.09,
            "completion_rate": 20.38
          },
          {
            "converted_user": 5599,
            "conversion_rate": 81.8,
            "completion_rate": 16.67
          }
        ],
        [
          {
            "converted_user": 33579,
            "conversion_rate": 100,
            "completion_rate": 100
          },
          {
            "converted_user": 25271,
            "conversion_rate": 75.26,
            "completion_rate": 75.26
          },
          {
            "converted_user": 6845,
            "conversion_rate": 27.09,
            "completion_rate": 20.38
          },
          {
            "converted_user": 5599,
            "conversion_rate": 81.8,
            "completion_rate": 16.67
          }
        ]
      ]
    }
  ],
  "by_field": "event.$Anything.$os",
  "by_values": [
    "$ALL",
    "iOS"
  ],
  "event_names": [
    "ViewHomePage",
    "ViewProduct",
    "SubmitOrder",
    "PayOrder"
  ],
  "report_update_time": "2017-04-21 11:13:47.703",
  "data_update_time": "2017-04-21 11:12:56.000",
  "data_sufficient_update_time": "2017-04-21 11:12:56.000"
}
```

* 使用 curl 示例 

```bash
curl 'https://golddemo.cloud.sensorsdata.cn/api/funnels/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '{
    "from_date":"2017-03-01",
    "to_date":"2017-03-31",
    "funnel_id":"220",
    "filter":{
        "conditions":[
            {
                "field":"event.BindCard.BankCard",
                "function":"equal",
                "params":[
                    "信用卡"
                ]
            },
            {
                "field":"event.$Anything.$province",
                "function":"equal",
                "params":[
                    "江苏省"
                ]
            }
        ],
        "relation":"and"
    },
    "by_field":"event.$Anything.$os_version"
}'
```

### 3.3 留存分析报告

> \[POST /retentions/report]

* Request (application/json) 

```javascript
{
    // 起始日期
    "from_date": "2018-04-30", 
    // 结束日期
    "to_date": "2018-05-02", 
    // 表示获取往后 N 个单位的留存
    "duration": "7", 
    // 第一个事件的信息
    "first_event": {
        // 事件名
        "event_name": "login"
    }, 
    // 第二个事件的信息
    "second_event": {
        // 事件名
        "event_name": "submitOrder", 
        // 事件的筛选条件
        "filter": {
            "conditions": [
                {
                    "field": "event.submitOrder.$lib", 
                    "function": "equal", 
                    "params": [
                        "Android"
                    ]
                }
            ],
            "relation":"and" 
        }
    }, 
    // （可选）同时显示第三个指标
    "measures": [
        {
            "event_name": "payOrder", 
            "aggregator": "unique"
        }
    ], 
    // （可选）用户的筛选条件
    "user_filter": {
        "conditions": [
            {
                "field": "user.sex", 
                "function": "equal", 
                "params": [
                    "男"
                ]
            }
        ],
        "relation":"and" 
    }, 
    // （可选）时间标识，例如上周，优先级高于 from_date 和 to_date
    "rangeText": "上周"
    // （可选）留存的单位，可以是 day/week/month
    "unit": "day", 
    // （可选）后续事件是否可以超出时间区间
    "extend_over_end_date": true, 
    // （可选）抽样因子，64为全量，32为2分之1抽样
    "sampling_factor": 64, 
    // （可选）是否计算流失，false为计算留存，true为计算流失
    "is_wastage": false, 
    "use_cache": true
}
```

* Response 200 (application/json) 

```javascript
{
    "by_field": "",
    "has_first_day": false,
    "rows": [
        {
            "by_value": "2018-04-30",
            "total_people": 95,
            "cells": [
                {
                    "people": 36,
                    "percent": 37.89,
                    "values": [
                        0
                    ]
                },
                {
                    "people": 6,
                    "percent": 6.32,
                    "values": [
                        5
                    ]
                }
            ]
        },
        {
            "by_value": "2018-05-01",
            "total_people": 91,
            "cells": [
                {
                    "people": 25,
                    "percent": 27.47,
                    "values": [
                        0
                    ]
                },
                {
                    "people": 1,
                    "percent": 1.1,
                    "values": [
                        1
                    ]
                }
            ]
        },
        {
            "by_value": "2018-05-02",
            "total_people": 62,
            "cells": [
                {
                    "people": 25,
                    "percent": 40.32,
                    "values": [
                        0
                    ]
                }
            ]
        }
    ],
    "report_update_time": "2018-05-02 17:00:21.355",
    "data_update_time": "2018-05-02 16:59:43.000",
    "data_sufficient_update_time": "2018-05-02 16:59:43.000",
    "truncated": false
}
```

* 使用 curl 示例 

```bash
curl 'https://golddemo.cloud.sensorsdata.cn/api/retentions/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '{
    "from_date": "2018-04-30", 
    "to_date": "2018-05-02", 
    "duration": "7", 
    "first_event": {
        "event_name": "login"
    }, 
    "second_event": {
        "event_name": "submitOrder", 
        "filter": {
            "conditions": [
                {
                    "field": "event.submitOrder.$lib", 
                    "function": "equal", 
                    "params": [
                        "Android"
                    ]
                }
            ], 
            "relation": "and"
        }
    }, 
    "measures": [
        {
            "event_name": "payOrder", 
            "aggregator": "unique"
        }
    ], 
    "user_filter": {
        "conditions": [
            {
                "field": "user.sex", 
                "function": "equal", 
                "params": [
                    "男"
                ]
            }
        ], 
        "relation": "and"
    }, 
    "unit": "day", 
    "extend_over_end_date": true, 
    "sampling_factor": 64, 
    "is_wastage": false, 
    "use_cache": true
}'
```

### 3.4 分布分析报告

> \[POST /addictions/report]

* Request (application/json) 

```javascript
{
    // 事件名称
    "event_name": "submitOrder",
    // 起始时间
    "from_date": "2018-04-30",
    // 结束时间
    "to_date": "2018-05-02",
    // 事件筛选条件
    "filter": {
        "conditions": [
            {
                "field": "event.submitOrder.$lib",
                "function": "equal",
                "params": [
                    "Android"
                ]
            }
        ],
        "relation":"and"
    },
    // 用户筛选条件
    "user_filter": {
        "conditions": [
            {
                "field": "user.sex",
                "function": "equal",
                "params": [
                    "男"
                ]
            }
        ],
        "relation":"and"
    },
    // （可选）时间标识，如：上周，优先级高于from_date、to_date
    "rangeText":"上周",
    // 抽样因子，64为全量，32为2分之1抽样
    "sampling_factor":64,
    // 事件单位，可以是 day/week/month
    "unit": "day", 
    // 测量类型,可以是times/period, period是当按小时数或者天数进行分布分析时使用
    "measure_type":"times",
    //测量类型如果是times，即可以自定义分桶，可省略
    "result_bucket_param": [
        2,
        3
    ]
}
```

* Response 200 (application/json) 

```javascript
{
    "by_field": "",
    "rows": [
        {
            "by_value": "2018-04-30",
            "total_people": 455,
            "cells": [
                {
                    "people": 436,
                    "percent": 95.82,
                    "bucket_end": 2
                },
                {
                    "people": 19,
                    "percent": 4.18,
                    "bucket_start": 2,
                    "bucket_end": 3
                }
            ]
        },
        {
            "by_value": "2018-05-01",
            "total_people": 499,
            "cells": [
                {
                    "people": 484,
                    "percent": 96.99,
                    "bucket_end": 2
                },
                {
                    "people": 15,
                    "percent": 3.01,
                    "bucket_start": 2,
                    "bucket_end": 3
                }
            ]
        },
        {
            "by_value": "2018-05-02",
            "total_people": 280,
            "cells": [
                {
                    "people": 273,
                    "percent": 97.5,
                    "bucket_end": 2
                },
                {
                    "people": 7,
                    "percent": 2.5,
                    "bucket_start": 2,
                    "bucket_end": 3
                }
            ]
        }
    ],
    "report_update_time": "2018-05-02 17:15:26.739",
    "data_update_time": "2018-05-02 17:14:10.000",
    "data_sufficient_update_time": "2018-05-02 17:14:10.000",
    "truncated": false
}
```

* 使用 curl 示例 

```bash
curl 'https://golddemo.cloud.sensorsdata.cn/api/addictions/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '{
    "event_name": "submitOrder", 
    "from_date": "2018-04-30", 
    "to_date": "2018-05-02", 
    "filter": {
        "conditions": [
            {
                "field": "event.submitOrder.$lib", 
                "function": "equal", 
                "params": [
                    "Android"
                ]
            }
        ], 
        "relation": "and"
    }, 
    "user_filter": {
        "conditions": [
            {
                "field": "user.sex", 
                "function": "equal", 
                "params": [
                    "男"
                ]
            }
        ], 
        "relation": "and"
    }, 
    "sampling_factor": 64, 
    "unit": "day", 
    "measure_type": "times", 
    "result_bucket_param": [
        2, 
        3
    ]
}'
```

### 3.5 用户路径分析报告

> \[POST /path/analytics/report]

* Request (application/json) 

```javascript
{
  // 起始事件是initial_event, 结束事件是termination_event
  "source_type": "initial_event",    
  // 起始事件和对起始事件的过滤
  "source_event": {        
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue",
          "params": []
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [        
    "event.BuyBullion.$country"
  ],
  // （可选）列数量的限制
  "col_limit": 20,
  // （可选）每列节点数限制
  "row_limit": 7,
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "user_filter": {},
  "bucket_params": {},
  "sampling_factor": 64,
  "session_interval": 1200,
  "use_cache": true
}
```

* Response 200 (application/json) 

```javascript
{
  "nodes": [
    [
      {
        "id": "0_StartApp",
        "event_name": "StartApp",
        "times": 27336
      }
    ],
    [
      {
        "id": "1_StartApp",
        "event_name": "StartApp",
        "times": 163
      },
      {
        "id": "1_BuyGold",
        "event_name": "BuyGold",
        "times": 118
      },
      {
        "id": "1_SaleGold",
        "event_name": "SaleGold",
        "times": 104
      },
      {
        "id": "1_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 37
      }
    ],
    [
      {
        "id": "2_SaleGold",
        "event_name": "SaleGold",
        "times": 68
      },
      {
        "id": "2_BuyGold",
        "event_name": "BuyGold",
        "times": 50
      },
      {
        "id": "2_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 18
      },
      {
        "id": "2_StartApp",
        "event_name": "StartApp",
        "times": 2
      }
    ],
    [
      {
        "id": "3_SaleGold",
        "event_name": "SaleGold",
        "times": 39
      },
      {
        "id": "3_BuyGold",
        "event_name": "BuyGold",
        "times": 23
      },
      {
        "id": "3_BuyBullion_$country_3392903",
        "event_name": "BuyBullion",
        "times": 1
      }
    ],
    [
      {
        "id": "4_StartApp",
        "event_name": "StartApp",
        "times": 1
      }
    ]
  ],
  "links": [
    [
      {
        "source": "0_StartApp",
        "target": "1_wastage",
        "is_wastage": true,
        "times": 26914
      },
      {
        "source": "0_StartApp",
        "target": "1_StartApp",
        "times": 163
      },
      {
        "source": "0_StartApp",
        "target": "1_BuyGold",
        "times": 118
      },
      {
        "source": "0_StartApp",
        "target": "1_SaleGold",
        "times": 104
      },
      {
        "source": "0_StartApp",
        "target": "1_BuyBullion_$country_3392903",
        "times": 37
      }
    ],
    [
      {
        "source": "1_StartApp",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 160
      },
      {
        "source": "1_StartApp",
        "target": "2_StartApp",
        "times": 2
      },
      {
        "source": "1_StartApp",
        "target": "2_BuyBullion_$country_3392903",
        "times": 1
      },
      {
        "source": "1_BuyGold",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 68
      },
      {
        "source": "1_BuyGold",
        "target": "2_BuyGold",
        "times": 50
      },
      {
        "source": "1_SaleGold",
        "target": "2_SaleGold",
        "times": 68
      },
      {
        "source": "1_SaleGold",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 36
      },
      {
        "source": "1_BuyBullion_$country_3392903",
        "target": "2_wastage",
        "is_wastage": true,
        "times": 20
      },
      {
        "source": "1_BuyBullion_$country_3392903",
        "target": "2_BuyBullion_$country_3392903",
        "times": 17
      }
    ],
    [
      {
        "source": "2_SaleGold",
        "target": "3_SaleGold",
        "times": 39
      },
      {
        "source": "2_SaleGold",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 29
      },
      {
        "source": "2_BuyGold",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 27
      },
      {
        "source": "2_BuyGold",
        "target": "3_BuyGold",
        "times": 23
      },
      {
        "source": "2_BuyBullion_$country_3392903",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 17
      },
      {
        "source": "2_BuyBullion_$country_3392903",
        "target": "3_BuyBullion_$country_3392903",
        "times": 1
      },
      {
        "source": "2_StartApp",
        "target": "3_wastage",
        "is_wastage": true,
        "times": 2
      }
    ],
    [
      {
        "source": "3_SaleGold",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 38
      },
      {
        "source": "3_SaleGold",
        "target": "4_StartApp",
        "times": 1
      },
      {
        "source": "3_BuyGold",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 23
      },
      {
        "source": "3_BuyBullion_$country_3392903",
        "target": "4_wastage",
        "is_wastage": true,
        "times": 1
      }
    ],
    [
      {
        "source": "4_StartApp",
        "target": "5_wastage",
        "is_wastage": true,
        "times": 1
      }
    ]
  ],
  "truncate_row": [],
  "truncate_col": false,
  "report_update_time": "2017-05-22 11:07:40.544",
  "data_update_time": "2017-05-22 11:06:54.000",
  "data_sufficient_update_time": "2017-05-22 11:06:54.000"
}
```

* 使用 curl 示例 

```bash
curl 'https://golddemo.cloud.sensorsdata.cn/api/path/analytics/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '{
  "source_type": "initial_event",
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue",
          "params": []
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [        
    "event.BuyBullion.$country"
  ],
  "col_limit": 20,
  "row_limit": 7,
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "user_filter": {},
  "bucket_params": {},
  "sampling_factor": 64,
  "session_interval": 1200,
  "use_cache": true
} '
```

### 3.6 属性分析报告

> \[POST /user/analytics/report]

* Request (application/json) 

```javascript
{
  "measures": [
    {
      "aggregator": "count",
      "field": ""
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "user.HasByGold",
        "function": "isTrue",
        "params": []
      }
    ]
  },
  "by_fields": [
    "user.IncomeLevel",
    "user.Gender"
  ],
  "sampling_factor": null,
  // 横轴分组指标
  "x_axis_field": "user.IncomeLevel",
  "use_cache": false
}
```

* Response 200 (application/json) 

```javascript
{
  "by_fields": [
    "user.Gender"
  ],
  "series": [
    "5000~10000",
    "3000~5000",
    "10000~20000",
    "0~3000",
    null
  ],
  "rows": [
    {
      "values": [
        [
          83169
        ],
        [
          27776
        ],
        [
          55699
        ],
        [
          27892
        ],
        [
          36106
        ]
      ],
      "by_values": [
        "男"
      ]
    },
    {
      "values": [
        [
          55363
        ],
        [
          18208
        ],
        [
          37030
        ],
        [
          18668
        ],
        [
          24090
        ]
      ],
      "by_values": [
        "女"
      ]
    },
    {
      "values": [
        [
          25864
        ],
        [
          8490
        ],
        [
          17327
        ],
        [
          8628
        ],
        [
          17353
        ]
      ],
      "by_values": [
        null
      ]
    }
  ],
  "num_rows": 3,
  "report_update_time": "2017-05-22 14:16:03.595",
  "data_update_time": "1970-01-01 08:00:00.000",
  "data_sufficient_update_time": "1970-01-01 08:00:00.000"
}
```

* 使用 curl 示例 

```bash
curl 'https://golddemo.cloud.sensorsdata.cn/api/user/analytics/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-H 'Content-Type: application/json' \
--data-binary '{
  "measures": [
    {
      "aggregator": "count",
      "field": ""
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "user.HasByGold",
        "function": "isTrue",
        "params": []
      }
    ]
  },
  "by_fields": [
    "user.IncomeLevel",
    "user.Gender"
  ],
  "sampling_factor": null,
  "x_axis_field": "user.IncomeLevel",
  "request_id": 1495433768121,
  "use_cache": false
}
'
```

## 4. 用户明细查询

用户明细系列接口用于查询某一个特定分析报告中的具体用户列表，请求的大部分参数与分析报告相同，新增的参数会在每个接口里具体说明。用户列表也支持 JSON 和 CSV 两种格式，默认式 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析的用户列表对应的 CSV 格式的 URL 为: /events/user/list?format=csv。

### 4.1 事件分析用户明细报告

> \[POST /events/user/list]

* Request (application/json) 

```javascript
{
  "measures": [
    {
      "aggregator": "unique",
      "event_name": "SaleGold"
    }
  ],
  "filter": {
    "conditions": [
      {
        "field": "event.SaleGold.$city",
        "function": "equal",
        "params": [
          "厦门市"
        ]
      },
      {
        "field": "event.SaleGold.$app_version",
        "function": "equal",
        "params": [
          "1.7"
        ]
      }
    ]
  },
  "by_fields": [
    "event.SaleGold.$app_version",
    "event.SaleGold.$screen_width"
  ],
  "rollup_date": false,
  "unit": "week",
  // 查看哪个分组的用户明细
  "slice_by_values": [
    "1.7",
    1080
  ], 
  // 查看哪天的用户明细
  "slice_date": "2015-08-18 00:00:00", 
  // 是否展示详情，如果 true，则会按照 profile 中的列返回，false 则只返回基本的 id 列
  "detail": true,
  // 默认值30，表示每页展示用户数，可不加    
  "num_per_page": 10,
  // 请求的页数 
  "page":1,
  // 限制返回的条数
  "limit": 100000,
  // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数 
  "all_page": true 
}
```

* Response 200 (application/json) 

```javascript
        {
           "users": [
            {
              "id": "1902482830",
              "first_id": "23e3ff2a3ff1e1bc",
              "second_id": "1696144579",
              "profiles": {
                "FavoriteFruits": [
                  "Raspberry",
                  "Orange"
                ],
                "$name": "陈爍簀",
                "IncomeLevel": "3000~5000",
                "$city": "德阳市",
                "$province": "四川省",
                "$signup_time": 1.432805251963E12,
                "Gender": "男",
                "Age": 20.0
              }
            },
            {
              "id": "3834577070",
              "first_id": "51b0fecc44b5c75b",
              "second_id": "1602971488",
              "profiles": {
                "FavoriteFruits": [
                  "Cranberry",
                  "Guava",
                  "cantaloupe"
                ],
                "$name": "周瀌狙",
                "IncomeLevel": "10000~20000",
                "$city": "嘉峪关市",
                "$province": "甘肃省",
                "$signup_time": 1.432799799529E12,
                "Gender": "女",
                "Age": 20.0
              }
            }
          ],
          "size": 2,
          "page_num": 1, // 页数，总人数/每页展示用户数
          "column_name":[
                "FavoriteFruits",
                "$name",
                "Age",
                "Gender",
                "IncomeLevel",
                "$signup_time",
                "$city",
                "$province"
                ]
        }
```

### 4.2 漏斗分析用户明细报告

> \[POST /funnels/user/list]

* Request (application/json) 

```javascript
        {
          "funnel_id": 158,
          "from_date": "2015-04-17",
          "to_date": "2015-07-16",
          "filter": {
            "conditions": [
              {
                "field": "event.$Anything.$lib_version",
                "function": "contain",
                "params": [
                  "0.1.0"
                ]
              },
              {
                "field": "event.$Anything.$lib",
                "function": "contain",
                "params": [
                  "python"
                ]
              },
              {
                "field": "user.Gender",
                "function": "equal",
                "params": [
                  "男"
                ]
              }
            ],
            "relation": "and"
          },
          "by_field": "event.SaleGold.$lib_version",
          // 用户明细的分组值
          "slice_by_value": "0.1.0",
          // 用户明细的步骤
          "slice_step": 0,
          // true 表示查看流失用户明细，false 表示转化用户
          "slice_wastage_user": false,
          // 是否展示详情，如果 true，则会按照 profile 中的列返回，false 则只返回基本的 id 列
          "detail": true,
          // 请求的页数 
          "page":1,
          // 每页数据条数
          "num_per_page": 30,
          // 限制返回的条数
          "limit": 100000,
          // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
          "all_page": true 
        }
```

* Response 200 (application/json) 

```javascript
        {
          "users": [
            {
              "id": "1902482830",
              "first_id": "23e3ff2a3ff1e1bc",
              "second_id": "1696144579",
              "profiles": {
                "FavoriteFruits": [
                  "Raspberry",
                  "Orange"
                ],
                "$name": "陈爍簀",
                "IncomeLevel": "3000~5000",
                "$city": "德阳市",
                "$province": "四川省",
                "$signup_time": 1.432805251963E12,
                "Gender": "男",
                "Age": 20.0
              }
            },
            {
              "id": "3834577070",
              "first_id": "51b0fecc44b5c75b",
              "second_id": "1602971488",
              "profiles": {
                "FavoriteFruits": [
                  "Cranberry",
                  "Guava",
                  "cantaloupe"
                ],
                "$name": "周瀌狙",
                "IncomeLevel": "10000~20000",
                "$city": "嘉峪关市",
                "$province": "甘肃省",
                "$signup_time": 1.432799799529E12,
                "Gender": "女",
                "Age": 20.0
              }
            }
          ],
          "size": 2,
          "page_num": 1,
          "column_name":[
                "FavoriteFruits",
                "$name",
                "Age",
                "Gender",
                "IncomeLevel",
                "$signup_time",
                "$city",
                "$province"
                ]
        }
```

### 4.3 留存分析用户明细报告

> \[POST /retentions/user/list]

* Request (application/json) 

```javascript
        {
          "first_event": {
            "event_name": "BuyGold",
            "filter": {
              "conditions": [
                {
                  "field": "event.BuyGold.$lib_version",
                  "function": "contain",
                  "params": [
                    "0.1.0"
                  ]
                }
              ]
            }
          },
          "second_event": {
            "event_name": "StartApp"
          },
          //是否流失用户，默认留存用户
          "is_wastage": false, 
          // 指定哪些用户属性，为空表示所有用户属性
          "profiles": [],
          "duration": 7,
          "from_date": "2015-07-21",
          "to_date": "2015-07-24",
          "unit": "day",
          "by_field": "event.SaleGold.$lib_version",
          // 用户明细分的分组值
          "slice_by_value": "0.1.0",
          // 查看第几天留存的用户明细，0 表示当天，null 表示全部
          // 表示随后第几天留存
          "slice_interval": 1,
          // 是否展示详情，如果 true，则会按照 profile 中的列返回，false 则只返回基本的 id 列
          "detail": true,
          // 请求的页数 
          "page":1,
          // 每页数据条数
          "num_per_page": 30,
          // 限制返回的条数
          "limit": 100000,
          // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
          "all_page": true
        }
```

* Response 200 (application/json) 

```javascript
        {
          "users": [
            {
              "id": "1902482830",
              "first_id": "23e3ff2a3ff1e1bc",
              "second_id": "1696144579",
              "profiles": {
                "FavoriteFruits": [
                  "Raspberry",
                  "Orange"
                ],
                "$name": "陈爍簀",
                "IncomeLevel": "3000~5000",
                "$city": "德阳市",
                "$province": "四川省",
                "$signup_time": 1.432805251963E12,
                "Gender": "男",
                "Age": 20.0
              }
            },
            {
              "id": "3834577070",
              "first_id": "51b0fecc44b5c75b",
              "second_id": "1602971488",
              "profiles": {
                "FavoriteFruits": [
                  "Cranberry",
                  "Guava",
                  "cantaloupe"
                ],
                "$name": "周瀌狙",
                "IncomeLevel": "10000~20000",
                "$city": "嘉峪关市",
                "$province": "甘肃省",
                "$signup_time": 1.432799799529E12,
                "Gender": "女",
                "Age": 20.0
              }
            }
          ],
          "size": 2,
          "page_num": 1, 
          "column_name":[
                "FavoriteFruits",
                "$name",
                "Age",
                "Gender",
                "IncomeLevel",
                "$signup_time",
                "$city",
                "$province"
                ]
        }
```

### 4.4 分布分析用户明细报告

> \[POST /addictions/user/list]

* Request (application/json) 

```javascript
        {
          "event_name": "BuyGold",
          "filter": {
            "conditions": [
              {
                "field": "event.BuyGold.$lib_version",
                "function": "contain",
                "params": [
                  "0.1.0"
                ]
              }
            ]
          },
          "rollup_date": false,
          "from_date": "2015-04-22",
          "to_date": "2015-04-22",
          "unit": "day",
          "by_field": "event.SaleGold.$lib_version",
          // 用户明细的分组信息
          "slice_by_value": "0.1.0",
          // 查看回访频率为多少的用户明细
          "slice_freq": 2,
          "detail": true,
          // 请求的页数 
          "page":1,
          // 每页数据条数
          "num_per_page": 30,
          // 限制返回的条数
          "limit": 100000,
          // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
          "all_page": true
        }
```

* Response 200 (application/json) 

```javascript
        {
          "users": [
            {
              "id": "1902482830",
              "first_id": "23e3ff2a3ff1e1bc",
              "second_id": "1696144579",
              "profiles": {
                "FavoriteFruits": [
                  "Raspberry",
                  "Orange"
                ],
                "$name": "陈爍簀",
                "IncomeLevel": "3000~5000",
                "$city": "德阳市",
                "$province": "四川省",
                "$signup_time": 1.432805251963E12,
                "Gender": "男",
                "Age": 20.0
              }
            },
            {
              "id": "3834577070",
              "first_id": "51b0fecc44b5c75b",
              "second_id": "1602971488",
              "profiles": {
                "FavoriteFruits": [
                  "Cranberry",
                  "Guava",
                  "cantaloupe"
                ],
                "$name": "周瀌狙",
                "IncomeLevel": "10000~20000",
                "$city": "嘉峪关市",
                "$province": "甘肃省",
                "$signup_time": 1.432799799529E12,
                "Gender": "女",
                "Age": 20.0
              }
            }
          ],
          "size": 2,
          "page_num": 1, 
          "column_name":[
                "FavoriteFruits",
                "$name",
                "Age",
                "Gender",
                "IncomeLevel",
                "$signup_time",
                "$city",
                "$province"
                ]
        }
```

### 4.5 用户分群/属性分析用户明细报告

> \[POST /users/list]

* Request (application/json) 

```javascript
{
  "filter": {
    "conditions": [
      {
        //field参数，
        //在用户分群中指分群名，如分群名为‘fenqun1’，field值为‘user.fenqun1’
        //在属性分析中指属性名，如属性名为‘birthday’，field值为‘user.birthday’
        "field": "user.test",
        "function": "isTrue"
      }
    ]
  },
  "profiles": [
    "user.$utm_source"
  ],
  // 请求的页数 
  "page":1,
  // 每页数据条数
  "num_per_page": 30,
  // 限制返回的条数
  "limit": 100000,
  // 是否返回所有用户，如果为 true，则会无视分页参数，否则需要加上分页参数
  "all_page": true
}
```

* Response 200 (application/json) 

```javascript
        {
          "users": [
            {
              "id": "1902482830",
              "first_id": "23e3ff2a3ff1e1bc",
              "second_id": "1696144579",
              "profiles": {
                "FavoriteFruits": [
                  "Raspberry",
                  "Orange"
                ],
                "$name": "陈爍簀",
                "IncomeLevel": "3000~5000",
                "$city": "德阳市",
                "$province": "四川省",
                "$signup_time": 1.432805251963E12,
                "Gender": "男",
                "Age": 20.0
              }
            },
            {
              "id": "3834577070",
              "first_id": "51b0fecc44b5c75b",
              "second_id": "1602971488",
              "profiles": {
                "FavoriteFruits": [
                  "Cranberry",
                  "Guava",
                  "cantaloupe"
                ],
                "$name": "周瀌狙",
                "IncomeLevel": "10000~20000",
                "$city": "嘉峪关市",
                "$province": "甘肃省",
                "$signup_time": 1.432799799529E12,
                "Gender": "女",
                "Age": 20.0
              }
            }
          ],
          "size": 2,
          "page_num": 1, 
          "column_name":[
                "FavoriteFruits",
                "$name",
                "Age",
                "Gender",
                "IncomeLevel",
                "$signup_time",
                "$city",
                "$province"
          ]
        }
```

这个接口也可以指定要查询的用户id，这样能获取指定用户的属性信息。

* Request (application/json) 

```javascript
        {
            "filter":{
                "conditions":[
                    {
                        "field":"user.test",
                        "function":"isTrue"
                    }
                ]
            },
            "users":["1902482830", "3834577070"],
            "profiles":[
                "user.$utm_source"
            ]            
        }
```

* Response 200 (application/json) 

```javascript
        {
          "users": [
            {
              "id": "1902482830",
              "first_id": "23e3ff2a3ff1e1bc",
              "second_id": "1696144579",
              "profiles": {
                "FavoriteFruits": [
                  "Raspberry",
                  "Orange"
                ],
                "$name": "陈爍簀",
                "IncomeLevel": "3000~5000",
                "$city": "德阳市",
                "$province": "四川省",
                "$signup_time": 1.432805251963E12,
                "Gender": "男",
                "Age": 20.0
              }
            },
            {
              "id": "3834577070",
              "first_id": "51b0fecc44b5c75b",
              "second_id": "1602971488",
              "profiles": {
                "FavoriteFruits": [
                  "Cranberry",
                  "Guava",
                  "cantaloupe"
                ],
                "$name": "周瀌狙",
                "IncomeLevel": "10000~20000",
                "$city": "嘉峪关市",
                "$province": "甘肃省",
                "$signup_time": 1.432799799529E12,
                "Gender": "女",
                "Age": 20.0
              }
            }
          ],
          "size": 2,
          "page_num": 1, 
          "column_name":[
                "FavoriteFruits",
                "$name",
                "Age",
                "Gender",
                "IncomeLevel",
                "$signup_time",
                "$city",
                "$province"
          ]
        }
```

### 4.6 用户路径用户明细报告

> \[POST /users/list]

* Request (application/json) 

```javascript
{
  "slice_element_filter": [
    {
      "slice_event_name": "StartApp",
      "slice_by_value": "8.1"
    }
  ],
  "next_slice_element_filter": [
    {
      "slice_event_name": "SaleGold",
      "slice_by_value": "1"
    }
  ], // 合计，后续事件统计和流失不需要这个过滤条件
  "session_level": "0", // 源端的层数
  "source_type": "initial_event",
  "source_event": {
    "event_name": "StartApp",
    "filter": {
      "conditions": [
        {
          "field": "event.StartApp.$wifi",
          "function": "isTrue"
        }
      ]
    }
  },
  "event_names": [
    "BuyBullion",
    "BuyGold",
    "SaleGold",
    "StartApp"
  ],
  "by_fields": [
    "event.SaleGold.$wifi",
    "event.StartApp.$os_version"
  ],
  "session_interval": "1200",
  "from_date": "2017-05-01",
  "to_date": "2017-05-22",
  "detail": true,
  "col_limit": "20",
  "row_limit": "7",
  "sampling_factor": 64,
  "is_aggregate": "false",     // 当前节点是否表示更多
  "edge_type": "ALL",    // 可以是WASTAGE，RETENTION和ALL，分别表示流失节点，后续事件统计，该节点合计人数
  "is_next_aggregate": "false", // 后续节点是否表示更多
  "num_per_page": 50,
  "all_page": true,
  "filter": {},
  "use_cache": false
}
```

* Response 200 (application/json) 

```javascript
        {
          "users": [
            {
              "id": "1902482830",
              "first_id": "23e3ff2a3ff1e1bc",
              "second_id": "1696144579",
              "profiles": {
                "FavoriteFruits": [
                  "Raspberry",
                  "Orange"
                ],
                "$name": "陈爍簀",
                "IncomeLevel": "3000~5000",
                "$city": "德阳市",
                "$province": "四川省",
                "$signup_time": 1.432805251963E12,
                "Gender": "男",
                "Age": 20.0
              }
            },
            {
              "id": "3834577070",
              "first_id": "51b0fecc44b5c75b",
              "second_id": "1602971488",
              "profiles": {
                "FavoriteFruits": [
                  "Cranberry",
                  "Guava",
                  "cantaloupe"
                ],
                "$name": "周瀌狙",
                "IncomeLevel": "10000~20000",
                "$city": "嘉峪关市",
                "$province": "甘肃省",
                "$signup_time": 1.432799799529E12,
                "Gender": "女",
                "Age": 20.0
              }
            }
          ],
          "size": 2,
          "page_num": 1, 
          "column_name":[
                "FavoriteFruits",
                "$name",
                "Age",
                "Gender",
                "IncomeLevel",
                "$signup_time",
                "$city",
                "$province"
          ]
        }
```

## 5. 自定义查询和用户行为列表

### 5.1 自定义查询

> \[GET /sql/query]

通过 SQL 进行自定义查询，表结构及自定义查询方法详见 [自定义查询](https://www.sensorsdata.cn/manual/query.html) 功能的介绍。

* Parameters
  * q: 查询的 SQL，例如 `SELECT event,time,user_id FROM events LIMIT 10`。
  * format: 可能的值包括
    * csv：默认格式
    * json：每行一个 JSON
    * event\_json：导出可以用于直接导入的 Event Track 格式的 Json（1.\*.3338 之后的版本支持）
    * profile\_json：导出可以用于直接导入的 Profile Set/Track Signup 格式的 Json（1.\*.3338 之后的版本支持）
    * sql：不直接返回数据，而是翻译为一条可以直接在 Spark/Impala/Hive 里执行的 SQL
* Response 200 (text/plain) 

```
        event    time    user_id
        RechargeCash    2015-09-02 13:01:00.125336    1731174795
        RechargeCash    2015-09-02 02:02:48.133002    1751664241
        RechargeCash    2015-09-02 13:01:53.308174    1784316911
        RechargeCash    2015-09-02 09:09:07.784417    1793667170
        RechargeCash    2015-09-02 09:09:42.420781    1807294808
        RechargeCash    2015-09-02 16:04:06.211421    1808422371
        RechargeCash    2015-09-02 08:08:44.646672    1810351186
        RechargeCash    2015-09-02 00:12:20.456509    1874214895
        RechargeCash    2015-09-02 02:02:38.494175    1897237370
        RechargeCash    2015-09-02 15:03:08.338102    2012805794
```

该接口和其它 API 的调用方式有所不同，q 参数直接用 GET/POST 参数传递即可，返回的数据为 **\t** 分隔。一个使用 curl 的例子如下:

```bash
curl 'https://saasdemo.cloud.sensorsdata.cn/api/sql/query?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-X POST \
--data-urlencode "q=SELECT * FROM events LIMIT 10" \
--data-urlencode "format=csv"
```

> 注意：如果查询的事件是预置事件，那么 $ 符号需要使用  进行转义。

### 5.2 用户行为列表

> \[POST /users/event/list]

获取一个或者多个用户在某一段时间内的详细行为信息。

* Request (application/json) 

```javascript
        {
          "users": [
            86015190,
            81952822,
            87961512
          ],
          "from_date": "2015-04-22",
          "to_date": "2015-04-22",
          // false 表示 users 参数指定的是内部的 user_id，true 表示传入的是 distinct_id
          "distinct_id": false
        }
```

* Response 200 (application/json) 

```javascript
        {
          "events": [
            {
              "user_id": "422337220",
              "event": "SaleGold",
              "time": 1432822231055,
              "properties": {
                "$province": "辽宁省",
                "$screen_height": 640.0,
                "$city": "大连市",
                "$os": "iOS",
                "$screen_width": 320.0,
                "$model": "iPhone 5",
                "$lib_version": "0.1.0",
                "$app_version": "1.3",
                "$manufacturer": "Apple",
                "$os_version": "7.0",
                "$wifi": 1.0,
                "$lib": "python",
                "SaleStep": 1.0
              }
            },
            {
              "user_id": "422337220",
              "event": "SaleGold",
              "time": 1432822232022,
              "properties": {
                "$province": "辽宁省",
                "$screen_height": 640.0,
                "$city": "大连市",
                "$os": "iOS",
                "$screen_width": 320.0,
                "$model": "iPhone 5",
                "$lib_version": "0.1.0",
                "$app_version": "1.3",
                "$manufacturer": "Apple",
                "$os_version": "7.0",
                "$wifi": 1.0,
                "$lib": "python",
                "GoldPrice": 240.34,
                "GoldWeight": 16153.0,
                "SaleStep": 2.0
              }
            }
          ]
   }
```