# Obtain app usage overview

Displays app usage data for a specific day, week, or month. You can view the app usage for the tenant or for a specific department.

**Notice**：1. This is only available to Business/Enterprise tenants.
2. Generally, the previous day's data is output at 10:00 a.m. each day.
3. Supported metrics include: App active users, cumulative users, new users, page views, and opens.
4. Only the data of users using Feishu v3.46 and later can be collected.
5. When data is viewed by department, the overall usage for the current department and its sub-departments will be displayed.
6. The calling frequency control is 100 times/min.

## Request

Facts | &nbsp;
---|---
HTTP URL | https://open.feishu.cn/open-apis/application/v6/applications/:app_id/app_usage/overview
HTTP Method | POST
Rate Limit | [100 per minute](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App
Required scopes<br>**To use this API, you must have at least 1 of the listed scopes.** | Obtain overview data of employees' app using(application:application.app_usage_stats.overview:readonly)

### Request header

Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`<br>**Value format**: "Bearer `access_token`"<br>**Example value**: "Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"

### Path parameters

Parameter | Type | Description
---|---|---
app_id | string | App ID<br>**Example value**: "cli_9f115af860f7901b"

### Query parameters

Parameter | Type | Required | Description
---|---|---|---
department_id_type | string | No | Type of department ID used in the call<br>**Example value**: open_department_id<br>**Optional values are**:<br>- department_id：Identify the department with the custom department_id<br>- open_department_id：Identify the department with open_department_id<br>**Default value**: `open_department_id`

### Request body

Parameter | Type | Required | Description
---|---|---|---
date | string | Yes | Queried date, in the format of yyyy-mm-dd. If cycle_type is 1, date can be any calendar day; if cycle_type is 2, date must be a Monday; if cycle_type is 3, date must be the first day of a month.<br>**Example value**: "2021-07-08"
cycle_type | int | Yes | Statistical type of active period<br>**Example value**: 1<br>**Optional values are**:<br>- 1：Daily active users. Data for the queried calendar day is returned.<br>- 2：Weekly active users. Data for the calendar week that contains the queried date is returned. If the week has not ended, data for the period from Monday to the day before the current date is returned. For example, if data for the week of July 5, 2021 is queried on July 15, 2021, data from July 5, 2021 to July 11, 2021 is returned. If data for the week of July 5, 2021 is queried on July 8, 2021, data from July 5, 2021 to July 7, 2021 is returned.<br>- 3：Monthly active users. Data for the calendar month that contains the queried date is returned. If the month has not ended, data for the period from the 1st of the month to the day before the current date is returned. For example, if data for July is queried on August 15, 2021, data from July 1, 2021 to July 31, 2021 is returned. If data for August is queried on August 15, 2021, data from August 1, 2021 to August 14, 2021 is returned.
department_id | string | No | Queried department ID. For how to obtain it, see [Department ID overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview).<br>-  If the department ID is empty, usage data for the current tenant is returned. If a department ID is specified, usage data for the current department (including sub-department users) is returned. <br>-  If department_id_type in the path parameter is empty or is the open_department_id, this field should be the open_department_id of the department. If department_id_type in the path parameter is the department_id, this field should be the department_id of the department.<br>**Example value**: "od-4e6ac4d14bcd5071a37a39de902c7141"
ability | string | Yes | Capability type. You can filter data by capability type to return corresponding activity data.<br>**Example value**: "app"<br>**Optional values are**:<br>- app：Returns overall app usage. Metric values include: uv: Active users; total_users: Cumulative users; new_users: New users; pv: page views in the app (gadget or web app); lifecycle: number of times the app (gadget or web app) is opened.<br>- mp：Returns gadget data. Metric values include: uv (active users of the gadget), pv (page views by users in the gadget), lifecycle (number of times the gadget was opened).<br>- h5：Returns web app data. Metric values include: uv (active users of web app), pv (page views in the web app), lifecycle (number of times the web app is opened).<br>- bot：Returns bot data. Metric values include: uv (active users of bot).

### Request body example
```json
{
    "date": "2021-07-26",
    "cycle_type": 1,
    "department_id": "od-bb009b4df5431400dc31d3bc8a37e069",
    "ability": "app"
}
```

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
items | application.app_usage\[\] | Overview of employees' use of the app
metric_name | string | Metric name
metric_value | int | Metric value

### Response body example
```json
{
    "code": 0,
    "data": {
        "items": [
            {
                "metric_name": "uv",
                "metric_value": 0
            },
            {
                "metric_name": "total_users",
                "metric_value": 2
            },
            {
                "metric_name": "new_users",
                "metric_value": 0
            },
            {
                "metric_name": "pv",
                "metric_value": 0
            },
            {
                "metric_name": "lifecycle",
                "metric_value": 0
            }
        ]
    },
    "msg": "success"
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
403 | 211004 | no authority for quota limit | Check whether it is a Business/Enterprise tenant.
400 | 211005 | invalid app id | Check the app ID.
400 | 211006 | invalid department id | Check the department ID.
400 | 211007 | invalid date format | Check whether the date field is in the format of "2021-07-01".
400 | 211008 | invalid ability | Check whether the ability value is correct.
400 | 211009 | invalid cycle type | Check whether the cycle_type value is correct.
400 | 211010 | invalid date range | Check whether the date value range is correct.
200 | 211011 | data not found | Data does not exist. Normal situation : No data was generated for this app on the date. support.

## Appendix-Description of Statistical Metrics

Metric | Definition | Notes
---|---|---
Active users of gadget | -   Number of unique users who open the gadget, deduplicated by user ID | -   Data of a certain day, week, or month can be viewed
Active users of web app | -   Number of unique users who open the web app, deduplicated by user ID<br>-   Only the data in the webview container of Feishu is counted, excluding the content in the container of a third-party browser | -   Data of a certain day, week, or month can be viewed
Active users of bot | -   Active users of the bot need to meet one of the following conditions:<br>-   Read the bot message<br>-   Sent a message to the bot<br>-   Combine and deduplicate by user ID in a single statistical period | -   Data of a certain day, week, or month can be viewed
Active users of app | -   Active users of the app need to meet one of the following conditions:<br>-   Opened the gadget<br>-   Opened H5<br>-   Sent a message to the bot<br>-   Read the bot message<br>-   Deduplicate and count by user ID in a single statistical period by combining all the above conditions | -   Data of a certain day, week, or month can be viewed
Cumulative users of app | - Number of users who have used the app | -   Only the cumulative number of users as of a certain day can be counted since it is not based on a time period.<br>-   That is, cycle_type can only be 1<br>- Only the cumulative number of users at the app granularity can be viewed. The gadget, web app, and bot are not separated.<br>-	That is, ability can only be an app<br>-   Note: Terminated personnel will be counted in the cumulative number of users, which therefore may be greater than the number of tenants.
New users of app | - Calculate the number of unique users who access the app in the period | -   Data of a certain day, week, or month can be viewed<br>- Only the cumulative number of users at the app granularity can be viewed. The gadget, web app, and bot are not separated.<br>-	That is, ability can only be an app
App opens | - Number of times the app (gadget or web app) is opened in Feishu | - Data is returned when ability is app, h5, or mp. No data is returned when ability is bot.<br>- Note: When a user actively closes the app or switches to another app for more than 5 min, this is counted as one open of the app.
Page views | - Number of times pages are viewed in the app (gadget or web app) | - Data is returned when ability is app, h5, or mp. No data is returned when ability is bot.<br>- Note: If a user switches to another app and then opens this app again in Feishu, this is counted as a new page view.

