Data APIs are open to all verified Official Accounts. With data APIs, developers can get data that is similar to but more flexible than that of the statistics module in the Official Accounts Platform and can also perform advanced processing operations as needed.

In the Official Account login authorization mechanism, "User Summary" APIs belong to the account service authorizations set.


  1. The API's Official Account database only stores data after December 1, 2014. Data before this time may not be found or is untrusted dirty data.

  2. Developers should save the data obtained by calling the API in their own databases. This will speed up the subsequent visit speed while reducing unnecessary loss in Weixin API call.

  3. To ensure that the Official Account data is calculated and processed, query the previous-day data each day before 08:00.

"User Summary" APIs refer to the APIs that get the user summary data in the data statistics module of the Official Accounts Platform. For the specific APIs, see the following list (excluding APIs related to user property data):

API Name Maximum Time Span API Calling Address (starting with https)
getusersummary 7
getusercumulate 7

The maximum time span is the maximum time range in which data can be acquired when an API is called. For example, a maximum time span of 7 means that data of the past 7 days can be acquired at a time. The actual value of access_token is obtained via the "Get access_token" API.

API Request Format

"User Summary" APIs (including the above APIs) post the following sample packet to API calling address:

    "begin_date": "2014-12-02", 
    "end_date": "2014-12-07"

Call Parameters

Parameter Required Description
access_token Yes The credential for API call
begin_date Yes Gets the start date of the data. The difference between begin_date and end_date must be less than the "maximum time span" (for example, when the maximum time span is 1, the difference between begin_date and end_date can only be 0). Otherwise, an error will occur.
end_date Yes Gets the end date of the data. The maximum value of end_date is yesterday.

Response Description

For a successful request, the response JSON packet of the API getusersummary is as follows:

    "list": [ 
            "ref_date": "2014-12-07", 
            "user_source": 0, 
            "new_user": 0, 
            "cancel_user": 0
        }//Followed by data of ref_date between begin_date and end_date

For a successful request, the response JSON packet of the API getusercumulate is as follows:

    "list": [ 
            "ref_date": "2014-12-07", 
            "cumulate_user": 1217056
        }, //Followed by data of ref_date between begin_date and end_date

Response Parameters

Parameter Description
ref_date The date of the data
user_source The user source. 0: Other sources. 1: Official Account search. 17: Contact Card. 30: QR code scanning. 43: The upper-right menu on the article page. 51: Following on the payment completion page. 57: The Official Account name on the article page. 75: Ads in the article of an official account. 78: Ads in Moments.
new_user The number of new users
cancel_user The number of users who unfollow the Official Account. The net increase in users is calculated by subtracting cancel_user from new_user.
cumulate_user The cumulative number of users

When an error occurs, Weixin will return the error code and other information. For the specific error code, see Common Error Codes.