Model query API

Last updated 10/03/2026

This document covers advanced AE features and involves many technical details. It's intended as a reference for users who are experienced with the related features. If you have questions about the content, contact your data consultant for one-on-one assistance.

The model query API is mainly used to obtain various data analysis reports.

For how to call the API, see the Open API documentation.

1. Common parameters

1. Property expressions

Almost all APIs use properties, for example, to filter, group, or aggregate by a property. Properties include event properties, user properties, and cohort properties. A property is usually expressed with two fields: the name and the table type. For example, the expression for the event property Province (#province) is as follows:

{
    "tableType":"event",
    "columnName":"#province"
}

User properties are similar. For example, to express User Level (user_level):

{
    "tableType":"user",
    "columnName":"user_level"
}

2. Filter expressions

Filter expressions also apply to most APIs. They express filter operations on certain events or users and use JSON in the following format:

{
  // Indicates whether the relation between the conditions in filts is OR or AND
  "relation": "and",
  // The list of specific conditions; there can be more than one
  "filts": [{
    // The left value of the condition, which is a property
    "tableType":"event",
    "columnName": "#os",
    // The comparison operator of the condition; here it means equal to
    "comparator": "equal",
    // The comparison values of the condition; there can be one or more, depending on the comparison operator
    "ftv": [
      "ios"
    ]
  },
  {
    "tableType":"user",
    "columnName":"user_level",
    "comparator": "equal",
    "ftv": [
      "5"
    ]
  }]
}

The following operators are currently supported:

• equal / notEqual

Means equal to / not equal to. Valid for string and numeric types. If ftv has multiple values, it is equivalent to In or Not In. For example, to filter users whose level is 3 or 5:

{
    "tableType":"user",
    "columnName":"user_level",
    "comparator": "equal",
    "ftv": ["3","5"]
}

• isTrue / isFalse

Valid only for Boolean types.

• isNull / notNull

Whether a property has a value. Valid for string and numeric types.

• include / notInclude

Means contains or doesn't contain a substring:

{
    "tableType":"user",
    "columnName":"channel",
    "comparator": "include",
    "ftv": ["Tencent MyApp"]
}

• less / greater / range: Mean less than / greater than / between two values (greater than or equal to the lower value and less than or equal to the upper value), where range is a closed interval at both ends. Valid for numeric and time types. For example, to filter all events where the remaining item quantity is between 3 and 9:

{
    "tableType":"event",
    "columnName":"count_left",
    "comparator": "range",
    "ftv": [3, 9]
}

Or, to filter all users whose last login time is between 2019-11-13 00:00~2019-11-23 00:00:

{
    "tableType":"user",
    "columnName":"latest_login_time",
    "comparator": "range",
    "ftv":["2019-11-13 00:00","2019-11-23 00:00"]
}

• regexMatch / notRegexMatch

Matches or doesn't match a regular expression. Valid only for string types.

• relativeCurrentBetween / relativeCurrentBefore

Operators for date types. They mean, respectively, between the past N days and the past M days relative to the current time / earlier than the past N days relative to the current time. For example, to filter all users whose registration time is earlier than the past 3 days relative to the current time:

{
    "tableType":"user",
    "columnName":"register_time",
    "comparator": "relativeCurrentBefore",
    "ftv": [3]
}

Or, to filter all users whose registration time is between the past 9 days and the past 3 days relative to the current time:

{
    "tableType":"user",
    "columnName":"register_time",
    "comparator": "relativeCurrentBetween",
    "ftv": [9, 3]
}

• relativeEventBefore / relativeEventAfter / relativeEventAbsolute

Operators for date types. They mean, respectively, within N units of time before the event occurred / within N units of time after the event occurred / within N units of time before or after the event occurred. For example, to filter events where the user's last login time is within 3 hours before the event occurred:

{
    "tableType":"user",
    "columnName":"latest_login_time",
    "comparator": "relativeEventBefore",
    "ftv": [3],
    "timeUnit": "hour"
}

• arrayIncludeItem / arrayNotIncludeItem

Operators for list types. They indicate whether a list contains certain elements

• arrayItemPos

An operator for list types. It indicates that the nth element of a list equals a certain value

• arrayIsNull / arrayNotNull

Operators for list types. They indicate whether a list exists

3. Table type enumeration values

• event

Event Table

• user

User Table

• cluster

Cohort/tag table