# Application and subscriber statistics

## getAppStats

Get the statistics of a specific app for a defined time period.

`POST` `https://api.pushwoosh.com/json/1.3/getAppStats`

##### Request body parameters

| Name   <div style="width:150px"></div>         | Required | Type   | Description                                                                                      |
|--------------|----------|--------|--------------------------------------------------------------------------------------------------|
| `auth`       | Yes      | string | [API access token](/developer/api-reference/api-access-token/) from Pushwoosh Control Panel.   |
| `application`| Yes      | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                                    |
| `datefrom`   | Yes      | string | Start date and time of the reporting period. Format: `Y-m-d H:i:s`.                            |
| `dateto`     | Yes      | string | End date and time of the reporting period. Format: `Y-m-d H:i:s`.                              |

##### Request example
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",    // required. API access token from Pushwoosh Control Panel
    "application": "XXXXX-XXXXX",      // required. Pushwoosh application code
    "datefrom": "2013-06-04 00:00:00", // required. Date and time, start of the reporting period
    "dateto": "2013-06-07 00:00:00"    // required. Date and time, end of the reporting period
  }
}
```



##### Response example

```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "request_id": "c93a202f439235f9adaaa06d651548ab"
  }
}
```
### Understanding the statistics

Statistics display registered actions for an application, device, or message within the specified timeframe.

Reports are automatically aggregated using the following rules:
- **Yearly**: If the period is longer than one year.
- **Monthly**: If the period is longer than one month.
- **Daily**: If the period is longer than one day.
- **Hourly**: If the period is longer than three hours.
- **Minutely**: In all other cases.

##### Action types

- **Application Level**: `_open_`, `_install_`
- **Device Level**: `_register_`, `_unregister_`
- **Message Level**: `_send_`, `_open_`

##### Response format
All statistics objects have the same format:
| Field   <div style="width:150px"></div>     | Type   | Description                                        |
|------------|--------|----------------------------------------------------|
| `formatter`| string | Report scale: yearly, monthly, daily, hourly, minutely. |
| `rows`     | list   | Contains report data for each registered action.  |

Each report row contains:

| Field  <div style="width:150px"></div>     | Type   | Description                              |
|-----------|--------|------------------------------------------|
| `count`   | int    | Number of registered actions.           |
| `action`  | string | The type of registered action.          |
| `datetime`| string | Formatted date: `Y-m-d H:i:s`.         |

### Retrieving scheduled request results

<Aside type="caution" title="Important">
As with every scheduled request, `/getAppStats` requires an additional [`/getResults`](/developer/api-reference/scheduled-requests#getresults) request.
</Aside>

##### Response body

| Field   <div style="width:150px"></div>   | Type   | Description                                                                                              |
|-------------|--------|----------------------------------------------------------------------------------------------------------|
| `request_id`| string | Scheduled request ID. Refer to [`/getResults`](/developer/api-reference/scheduled-requests#getresults) for more details. |

##### Scheduled (/getResults) response body

| Field   <div style="width:150px"></div>        | Type       | Description                       |
|--------------|------------|-----------------------------------|
| `applications`| dictionary | Statistics for applications.    |
| `devices`     | dictionary | Statistics for devices.         |
| `messages`    | dictionary | Statistics for messages.        |

##### Example 
```json 
{
  "error": {
    "code": 0,
    "message": "OK"
  },
  "json_data": {
    "applications": {
      "formatter": "hourly",
      "rows": [{
        "count": 0,
        "action": "open",
        "datetime": "2013-06-06 00:00:00"
      }, {
        ...
      }]
    }
  }
}
```




## getApplicationSubscribersStats

Displays the app's subscribers list grouped by the types of their devices.

`POST` `https://api.pushwoosh.com/json/1.3/getApplicationSubscribersStats`

##### Request Body

| Name    <div style="width:150px"></div>        | Required | Type   | Description                                                                                      |
|--------------|----------|--------|--------------------------------------------------------------------------------------------------|
| `auth`       | Yes      | string | [API access token](/developer/api-reference/api-access-token/) from Pushwoosh Control Panel.   |
| `application`| Yes      | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                                     |  

**Request example**

```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // required. API access token from Pushwoosh Control Panel
    "application": "XXXXX-XXXXX"    // required. Pushwoosh application code
  }
}
```

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "IOS": 1,
    "ANDROID": 1,
    "OSX": 0,
    "WINDOWS": 0,
    "AMAZON": 0,
    "SAFARI": 0,
    "FIREFOX": 0
  }
}
```
</TabItem>
</Tabs>



## getSubscribersStatistics

Retrieves app subscribers stats for a time period.

`POST` `https://api.pushwoosh.com/api/v2/statistics/application/getSubscribersStatistics`

##### Headers

| Name       <div style="width:150px"></div>        | Required | Description                                                                                                  |  
|-----------------|----------|--------------------------------------------------------------------------------------------------------------|  
| Authorization   | Yes      | [API access token](/developer/api-reference/api-access-token/) in the format: `Key PKX.......NHg`.          |  
| Content-Type    | Yes      |  Must be set to `application/json`.                                                                           |  

##### Request body parameters

| Name       <div style="width:150px"></div>         | Required | Type   | Description                                                              |  
|------------------|----------|--------|--------------------------------------------------------------------------|  
| application_code | Yes      | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                     |  
| timestamp_from   | Yes      | string | Start date and time of the stats period (format: `YYYY-MM-DD hh:mm:ss`, UTC+0). |  
| timestamp_to     | Yes      | string | End date and time of the stats period (format: `YYYY-MM-DD hh:mm:ss`, UTC+0).   |  

**Example request**
```shell
curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/application/getSubscribersStatistics' \
--header 'Authorization: Key 3a2X......828JreCk48f' \
--header 'Content-Type: application/json' \
--data-raw '{
   "application_code": "12345-67890",        // Pushwoosh app code
   "timestamp_from": "2022-08-01 00:00:00",  // UTC+0
   "timestamp_to": "2022-09-01 00:00:00"     // UTC+0
}'
```

**Example response**
```json
{
  "statistics": [{
    "timestamp": "YYYY-MM-DD hh:mm:ss", // UTC+0
    "platform": 1,
    "push_enabled": 100,
    "push_disabled": 100
  }]
}
```
**Response codes** 
<Tabs>
  <TabItem label="200: OK">
    ```json
    {
      "statistics": [{
        "timestamp": "YYYY-MM-DD hh:mm:ss",
        "platform": 1,
        "push_enabled": 100,
        "push_disabled": 100
      }]
    }
    ```

    **Explanation**: The request was successful, and the statistics are returned.
  </TabItem>

  <TabItem label="400: Bad Request">
    ```json
    {
      // Response
    }
    ```

    **Explanation**: The request had invalid syntax or parameters.
  </TabItem>

  <TabItem label="500: Internal Server Error">
    ```json
    {
      // Response
    }
    ```

    **Explanation**: The server encountered an error. Try again later.
  </TabItem>

  <TabItem label="401: Unauthorized">
    ```json
    {
      // Response
    }
    ```

    **Explanation**: Authentication failed. Check your API key or token.
  </TabItem>

  <TabItem label="403: Forbidden">
    ```json
    {
      // Response
    }
    ```

    **Explanation**: Access denied for the specified app code.
  </TabItem>

  <TabItem label="404: Not Found">
    ```json
    {
      // Response
    }
    ```

    **Explanation**: The app code was not found or doesn't exist.
  </TabItem>
</Tabs>

### Timestamp interval rules  

<Aside type="note">
Please take into consideration that the intervals between timestamps in the response depend on the period you send in your request as follows:

* if you request the stats for a period longer than one year, the stats timestamps interval will be a year
* if the stats period equals a year, the interval between response's timestamps equals a month
* for periods longer than a month but less than a year, stats for every day will be returned
* for periods less than a month, the response will include stats for every hour
</Aside>

| Requested period   <div style="width:350px"></div>    | Interval in response   <div style="width:350px"></div>   |  
|-------------------|--------------------|  
| More than 1 year  | 1 year              |  
| 1 year           | 1 month             |  
| 1 month - 1 year | 1 day               |  
| Less than 1 month| 1 hour              |