# Retention Analysis Model API
Call method See Call method description in Open API doc.
You can read the retention analysis in the user manual to understand the usage scenario.
# Retention Analysis Query
Interface URL
/open/retention-analyze?token=xxx
Request method
POST
Content-Type
application/json
Request Query Parameter
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| token | xxx | String | Yes | token |
# Request Body Parameter
{
"eventView":{
"endTime":"2021-10-30 23:59:59",
"filts":[
{
"columnDesc":"app version",
"columnName":"app_version",
"comparator":"equal",
"filterType":"SIMPLE",
"ftv":[
"V1.0"],
"specifiedClusterDate":"2022-01-24",
"tableType":"event",
"timeUnit":""
}],
"firstDayOfWeek":1,
"groupBy":[
{
"columnDesc": "browser",
"columnName":"browser",
"propertyRange":"",
"specifiedClusterDate":"2022-01-24",
"tableType":"event"
}],
"recentDay":"",
"relation":"and",
"startTime":"2021-10-01 00:00:00",
"statType":"retention",
"taIdMeasureVo":{
"columnDesc":"user only ID",
"columnName":"#user_id",
"tableType":"event"
},
"timeParticleSize":"week",
"unitNum":1
},
"events":[
{
"eventName":"login",
"eventNameDisplay":"",
"filts":[
{
"columnDesc":"app_version",
"columnName":"app_version",
"comparator":"equal",
"filterType":"SIMPLE",
"ftv":["V1.0"],
"specifiedClusterDate":"2022-01-26",
"tableType":"event",
"timeUnit":""
}],
"relation":"and",
"relationUser":"and",
"type":"first"
},
{
"eventName":"logout",
"eventNameDisplay":"",
"filts":[
],
"relation":"and",
"relationUser":"and",
"type":"second"
},
{
"analysis":"TOTAL_TIMES",
"analysisDesc":"total number",
"eventName":"activity_attend",
"eventNameDisplay":"",
"filts":[
],
"quota":"",
"relation":"and",
"relationUser":"and",
"type":"simultaneous_display"
}],
"projectId": 377,
"limit": 2,
"timeoutSeconds": 10,
"useCache": true
}
# Request Parameter Description
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| eventView | - | Object | Yes | Grouping properties |
| ∟ endTime | 2021-10-30 23:59:59 | String | No | End time (format: yyyy-MM-dd HH: mm: ss), valid when the relative time is empty |
| ∟ filts | - | List | No | Global filter |
| ∟ columnDesc | App version | String | No | Field display name |
| ∟ columnName | app_version | String | Yes | Field name |
| ∟ comparator | equal | String | Yes | Reference: Filtered expression for model query API |
| ∟ filterType | SIMPLE | String | No | Filter mode, SIMPLE: simple, COMPOUND: composite |
| ∟ ftv | ["V1.0"] | List | No | Property comparison value |
| ∟ specifiedClusterDate | 2022-01-24 | String | No | Cluster specified date |
| ∟ tableType | event | String | Yes | Table type, event: transaction table, user: user table |
| ∟ timeUnit | String | No | Property comparison units, valid for relativeEvent * only: day, hour, minute | |
| ∟ firstDayOfWeek | 1 | Integer | No | When timeParticleSize is week, specify the first day of the week, 1: Monday, 2: Tuesday,.., 7: Sunday, minimum 1, maximum 7 |
| ∟ groupBy | - | List | No | Group attributes, can have zero or more |
| ∟ columnDesc | Browser | String | No | Field display name |
| ∟ columnName | browser | String | Yes | Field name |
| ∟ propertyRange | String | No | Custom attribute interval | |
| ∟ specifiedClusterDate | 2022-01-24 | String | No | Cluster specified date |
| ∟ tableType | event | String | Yes | Table type, event: transaction table, user: user table |
| ∟ recentDay | String | No | Relative time (this item cannot be empty at the same time as the start time and the end time) | |
| ∟ relation | and | String | No | Logical relationship, and: logical and, or: logical or |
| ∟ startTime | 2021-10-01 00:00:00 | String | No | Start time (format: yyyy-MM-dd HH: mm: ss), valid when the relative time is empty |
| ∟ statType | retention | String | Yes | Statistics type, retention: retention, loss: lost |
| ∟ taIdMeasureVo | - | Object | No | Analyze subject configuration |
| ∟ columnDesc | User unique ID | String | No | Field display name |
| ∟ columnName | #user_id | String | Yes | Field name |
| ∟ tableType | event | String | Yes | Table type, event: transaction table, user: user table |
| ∟ timeParticleSize | week | String | Yes | Unit of time for analysis Press 1 minute Minute 5: Press 5 minutes (v3.5 starts to support) Minute 10: Press 10 minutes (v3.5 start support) By the hour By day Week: by week Month: by month Total: total |
| ∟ unitNum | 1 | Integer | Yes | Retention period |
| events | - | List | Yes | List of event indicators |
| ∟ eventName | login | String | Yes | Event type, in particular, you can use anyEvent to represent any event |
| ∟ eventNameDisplay | String | No | Event display name | |
| ∟ filts | - | List | No | List of conditions |
| ∟ columnDesc | app_version | String | No | Field display name |
| ∟ columnName | app_version | String | Yes | Field name |
| ∟ comparator | equal | String | Yes | Reference: Filtered expression for model query API |
| ∟ filterType | SIMPLE | String | No | Filter mode, SIMPLE: simple, COMPOUND: composite |
| ∟ ftv | ["V1.0"] | List | No | Property comparison value |
| ∟ specifiedClusterDate | 2022-01-26 | String | No | Cluster specified date |
| ∟ tableType | event | String | Yes | Table type, event: transaction table, user: user table |
| ∟ timeUnit | String | No | Filter time unit | |
| ∟ relation | and | String | No | Logical relationship, and: logical and, or: logical or |
| ∟ relationUser | and | String | No | User filtering logical relationships, and: logical and, or: logical or |
| ∟ type | first | String | Yes | Retention event type, First: Initial event Second: Return visit event simultaneous_display: Simultaneous display init_date_stat: Initial date indicator |
| projectId | 377 | Integer | Yes | Project ID |
| limit | 2 | Integer | No | Maximum number of groups per analysis object, optional parameters, default is 1000, maximum is 10000 |
| timeoutSeconds | 10 | Integer | No | Request timed out parameter, timeout cancels query task |
| useCache | true | Boolean | No | Use cache, optional parameter, default is true |
Also show the aggregation method analysis value:
| Value | Description | Whether properties are required |
|---|---|---|
| TOTAL_TIMES | Total number | No |
| TRIG_USER_NUM | Number of users triggered | No |
| PER_CAPITA_TIMES | Number of times per capita | No |
| SUM | Sum of values | Yes |
| FOR _ CAPITA _ NUM | Per capita | Yes |
| STAGE_ACC | Accumulated sum of stages | Yes |
| STAGE_ACC_PCV | Stage cumulative average | Yes |
| TRUE | True number | Yes |
| FALSE | False number | Yes |
| IS_NOT_EMPTY | Not an empty number | Yes |
| IS_EMPTY | Null number | Yes |
# Successful Response Example
{
"data": {
"result_generate_time": "2022-01-01 00:00:00",
"state_avg": {
"0": [
{
"groupCols": [
"total"
],
"initNum": 0,
"isTotal": 1,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"0.998"
]
},
{
"groupCols": [
"Chrome"
],
"initNum": 0,
"isTotal": 0,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"0.9981"
]
}
],
"1": [
{
"groupCols": [
"total"
],
"initNum": 0,
"isTotal": 1,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"1"
]
},
{
"groupCols": [
"Chrome"
],
"initNum": 0,
"isTotal": 0,
"lastValidDateVerticalIndexs": [
"-",
"4"
],
"values": [
"-",
"1"
]
}
],
"2": [
{
"groupCols": [
"total"
],
"initNum": 0,
"isTotal": 1,
"lastValidDateVerticalIndexs": [],
"values": [
"-",
"132405.4"
]
},
{
"groupCols": [
"Chrome"
],
"initNum": 0,
"isTotal": 0,
"lastValidDateVerticalIndexs": [],
"values": [
"-",
"66343.2"
]
}
]
},
"x": [
"2021-09-27",
"2021-10-04",
"2021-10-11",
"2021-10-18",
"2021-10-25"
],
"y": {
"0": {
"2021-09-27": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7388,
"isTotal": 1,
"values": [
"7388",
"7374"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3647,
"isTotal": 0,
"values": [
"3647",
"3642"
]
}
],
"2021-10-04": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7861,
"isTotal": 1,
"values": [
"7861",
"7844"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3939,
"isTotal": 0,
"values": [
"3939",
"3930"
]
}
],
"2021-10-11": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8013,
"isTotal": 1,
"values": [
"8013",
"7994"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4062,
"isTotal": 0,
"values": [
"4062",
"4054"
]
}
],
"2021-10-18": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8553,
"isTotal": 1,
"values": [
"8553",
"8543"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4225,
"isTotal": 0,
"values": [
"4225",
"4218"
]
}
],
"2021-10-25": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7414,
"isTotal": 1,
"values": [
"7414",
"7397"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3741,
"isTotal": 0,
"values": [
"3741",
"3733"
]
}
]
},
"1": {
"2021-09-27": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7388,
"isTotal": 1,
"values": [
"7388",
"7388"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3647,
"isTotal": 0,
"values": [
"3647",
"3647"
]
}
],
"2021-10-04": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7861,
"isTotal": 1,
"values": [
"7861",
"7861"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3939,
"isTotal": 0,
"values": [
"3939",
"3939"
]
}
],
"2021-10-11": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8013,
"isTotal": 1,
"values": [
"8013",
"8013"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4062,
"isTotal": 0,
"values": [
"4062",
"4062"
]
}
],
"2021-10-18": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8553,
"isTotal": 1,
"values": [
"8553",
"8553"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4225,
"isTotal": 0,
"values": [
"4225",
"4225"
]
}
],
"2021-10-25": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7414,
"isTotal": 1,
"values": [
"7414",
"7414"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3741,
"isTotal": 0,
"values": [
"3741",
"3741"
]
}
]
},
"2": {
"2021-09-27": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7388,
"isTotal": 1,
"values": [
"0",
"125324"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3647,
"isTotal": 0,
"values": [
"0",
"62105"
]
}
],
"2021-10-04": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7861,
"isTotal": 1,
"values": [
"0",
"132130"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3939,
"isTotal": 0,
"values": [
"0",
"65971"
]
}
],
"2021-10-11": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8013,
"isTotal": 1,
"values": [
"0",
"134691"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4062,
"isTotal": 0,
"values": [
"0",
"68566"
]
}
],
"2021-10-18": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 8553,
"isTotal": 1,
"values": [
"0",
"144030"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 4225,
"isTotal": 0,
"values": [
"0",
"71345"
]
}
],
"2021-10-25": [
{
"groupCols": [
"total"
],
"includeToday": false,
"initNum": 7414,
"isTotal": 1,
"values": [
"0",
"125852"
]
},
{
"groupCols": [
"Chrome"
],
"includeToday": false,
"initNum": 3741,
"isTotal": 0,
"values": [
"0",
"63729"
]
}
]
}
},
"z": [
"login",
"logout",
"activity_attend"
]
},
"return_code": 0,
"return_message": "success"
}
# Response Parameter Description
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | 0 | Integer | Return code |
| return_message | success | String | Return information |
| data | - | Object | Return result |
| ∟ result_generate_time | 2022-01-01 00:00:00 | String | Calculation result generation time |
| ∟ state_avg | - | Object | Result map with key as type and value as retention grouping |
| ∟ {type} | - | List | Type value, 0: retention, 1: loss, 2: statistics |
| ∟ groupCols | ["Overall"] | List | Grouping columns |
| ∟ initNum | 0 | Integer | Initial value |
| ∟ isTotal | 1 | Integer | Is it summary, 1: yes, 0: no |
| ∟ lastValidDateVerticalIndexs | ["-", "4"] | List | Last Effective Date Index |
| ∟ values | ["-", "0.998"] | List | Value list, "-" or number |
| ∟ x | ["2021-09-27"] | List | Date List |
| ∟ y | - | Object | Y-axis data |
| ∟ {type} | - | Object | Type value, 0: retention, 1: loss, 2: statistics |
| ∟ {date} | - | List | Key is date |
| ∟ groupCols | ["Overall"] | List | Grouping columns |
| ∟ includeToday | false | Boolean | Does it include today |
| ∟ initNum | 7388 | Integer | Initial value |
| ∟ isTotal | 1 | Integer | Is it summary, 1: yes, 0: no |
| ∟ values | ["7388"] | List | Value list |
| ∟ z | ["login"] | List | List of event names |
Error Response Example
{
"return_code": -1008,
"return_message": "The parameter (token) is empty"
}
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | -1008 | Integer | Return code |
| return_message | The parameter (token) is empty | String | Return information |
# Retention Analysis User List
Interface URL
/open/retention-user-list?token=xxx
Request method
POST
Content-Type
application/json
Request Query Parameter
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| token | xxx | String | Yes | token |
# Request Body Parameter
{
"projectId": 0,
"eventView": {
"startTime": "2019-11-24 00:00:00",
"endTime": "2019-11-26 00:00:00",
"recentDay": "1-3",
"statType": "retention",
"timeParticleSize": "day",
"unitNum": 7,
"groupBy": [
{
"columnName": "#province",
"tableType": "event"
}
]
},
"events": [
{
"type": "first",
"relation": "and",
"eventName": "player_register",
"filts": [
{
"columnName": "#province",
"comparator": "equal",
"ftv": [
"Jiangsu",
"Shanghai"
],
"tableType": "event"
},
{
"columnName": "user_level",
"comparator": "greater",
"ftv": [
"2"
],
"tableType": "user"
}
]
},
{
"type": "second",
"relation": "and",
"eventName": "obtain_diamond",
"filts": [
{
"columnName": "#os",
"comparator": "equal",
"ftv": [
"android"
],
"tableType": "event"
},
{
"$ref": "$.events[0].filts[1]"
}
]
}
],
"sliceDate": "2019-11-26",
"sliceInterval": 3,
"timeoutSeconds": 10
}
# Request Parameter Description
| Parameter name | Sample value | Parameter type | Is required | Parameter description |
|---|---|---|---|---|
| projectId | 0 | String | Yes | Parameter description |
| eventView | - | Object | Yes | Group property table |
| ∟ startTime | 2019-11-24 00:00:00 | String | No | Start time (format: yyyy-MM-dd HH: mm: ss), valid when the relative time is empty |
| ∟ endTime | 2019-11-26 00:00:00 | String | No | End time (format: yyyy-MM-dd HH: mm: ss), valid when the relative time is empty |
| ∟ recentDay | 1-3 | String | No | Relative time (this item cannot be empty at the same time as the start time and the end time) |
| ∟ statType | retention | String | Statistics type, retention: retention, loss: lost | |
| ∟ timeParticleSize | day | String | Yes | Unit of time for analysis Press 1 minute Minute 5: Press 5 minutes (v3.5 starts to support) Minute 10: Press 10 minutes (v3.5 start support) By the hour By day Week: by week Month: by month Total: total |
| ∟ unitNum | 7 | Integer | Retention period | |
| ∟ groupBy | - | List | No | Group attributes, can have zero or more |
| ∟ columnName | #province | String | Yes | Field name |
| ∟ tableType | event | String | Yes | Table type, event: transaction table, user: user table |
| events | List | Yes | List of event indicators | |
| ∟ type | first | String | Yes | First: Initial event Second: Return visit event simultaneous_display: Simultaneous display init_date_stat: Initial date indicator |
| ∟ eventName | player_register | String | Yes | Event type, in particular, you can use anyEvent to represent any event |
| ∟ relation | and | String | No | Logical relationship, and: logical and, or: logical or |
| ∟ filts | - | List | No | Filter List |
| ∟ columnName | #province | String | Yes | Field name |
| ∟ comparator | equal | String | Yes | Reference: Filtered expression for model query API |
| ∟ ftv | ["Jiangsu Province"] | List | No | Property comparison value |
| ∟ tableType | event | String | Yes | Table type, event: transaction table, user: user table |
| sliceDate | "2019-11-26" | String | No | Event date |
| sliceInterval | 3 | List | Yes | Period subscript 0: Initial event number of users 1: The day After 2:1 After 3:2 |
| timeoutSeconds | 10 | Integer | No | Request timed out parameter, timeout cancels query task |
# Successful Response Example
{
"data": {
"datalist": [
{
"#account_id": "v47739399",
"#distinct_id": "v88658799",
"user_level": 11,
"register_time": "2019-11-26 19:13:20",
"diamond_num": 1182,
"latest_login_time": "2019-11-26 20:16:19",
"channel": "Huawei App store",
"#user_id": 20459799
},
{
"#account_id": "i7819568",
"#distinct_id": "i14522048",
"user_level": 4,
"register_time": "2019-11-26 23:56:17",
"diamond_num": 1006,
"latest_login_time": "2019-11-26 23:59:59",
"channel": "360 Mobile Assistant",
"#user_id": 3351248
},
{
"#account_id": "g7812426",
"#distinct_id": "g14508786",
"user_level": 14,
"register_time": "2019-11-26 17:54:13",
"diamond_num": 245,
"first_recharge_time": "2019-11-26 18:08:58",
"latest_login_time": "2019-11-26 20:16:19",
"channel": "Xiaomi App stor",
"#user_id": 3348186
},
{
"#account_id": "a7812000",
"#distinct_id": "a14508000",
"user_level": 3,
"register_time": "2019-11-26 17:27:28",
"diamond_num": 1153,
"latest_login_time": "2019-11-26 18:45:58",
"channel": "app store",
"#user_id": 3348000
}
],
"columMeta": {
"#account_id": "account ID",
"#distinct_id": "visitor ID",
"user_level": "user level",
"register_time": "register time",
"diamond_num": "diamond number",
"first_recharge_time": "first recharge time",
"latest_login_time": "lastest login time",
"channel": "channel"
}
},
"return_code": 0,
"return_message": "success"
}
# Response Parameter Description
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | 0 | Integer | Return code |
| return_message | success | String | Return information |
| data | - | Object | Return result |
| data.datalist | - | List | User Information |
| data.columMeta | - | Map | Field meaning mapping |
Error Response Example
{
"return_code": -1008,
"return_message": "The parameter (token) is empty"
}
| Parameter name | Sample value | Parameter type | Parameter description |
|---|---|---|---|
| return_code | -1008 | Integer | Return code |
| return_message | The parameter (token) is empty | String | Return information |