Get top 10 apps by usage duration

Tool Name: airdroid_business_get_top_10_apps_by_usage_duration

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Reports & Analytics

Quick Start (Copy & Use)

In one sentence: Get the Top 10 apps by usage duration statistics for devices within a specified date range

What you need: StartDate (start date), EndDate (end date)

Success criteria: StatusCode=200 and ErrorMessage="" and AppUsageDuration.has_data="Data available"

What to do next: Analyze app usage based on the apps array, or combine with Get All Devices to filter specific devices

Minimal request example:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31"
}

Minimal response example:

{
  "AppUsageDuration": {
    "has_data": "Data available",
    "apps": [
      {
        "pkg_id": "com.facebook.katana",
        "duration": 3600,
        "app_name": "Facebook",
        "icon_url": "https://example.com/icon.png"
      },
      {
        "pkg_id": "com.whatsapp",
        "duration": 2400,
        "app_name": "WhatsApp",
        "icon_url": "https://example.com/whatsapp.png"
      }
    ]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Query All Devices App Usage for the Last 7 Days

Scenario: Quick overview of app usage patterns

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03"
}

Recipe 2: Filter App Usage by Group

Scenario: View app usage for a specific group only (e.g., Sales department)

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "GroupIds": [100]
}

GroupIds can be obtained via the Get a Group ID by Group Name tool

Recipe 3: Filter Devices by Keyword

Scenario: Only count app usage duration for Samsung devices

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "Keyword": "Samsung"
}

Keyword supports fuzzy matching on device_name, group_name, model, manu, and other fields

1. Overview

1.1 Description

Get app usage duration statistics for devices within a specified date range, returning the Top 10 apps ranked by usage duration.

1.2 When to Use

• App usage analysis: Understand which apps employees/devices use most frequently
• Work efficiency assessment: Analyze whether devices are being used for work-related apps
• Policy development basis: Develop device usage policies based on app usage patterns

1.3 Execution Mode & Response

This is a synchronous operation that returns results immediately upon invocation.

• Return value: AppUsageDuration object containing app usage duration data
• Data scope: Returns Top 10 apps (sorted by usage duration descending)

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`StartDate`

• Type: string
• Format: YYYY-MM-DD (e.g., 2026-01-01)
• Constraints:
  • Cannot be a future date
  • Cannot query data older than 30 days

`EndDate`

• Type: string
• Format: YYYY-MM-DD (e.g., 2026-01-31)
• Constraints:
  • Cannot be earlier than StartDate
  • Cannot be a future date
  • Date range with StartDate cannot exceed 30 days

`GroupIds`

• Type: number-array
• How to obtain: Via the Get a Group ID by Group Name tool
• Example:

  [100, 101]

`Keyword`

• Type: string
• Search type: Fuzzy match (case-insensitive)
• Searchable fields: device_name, group_name, group_path, note, device_id, snid, imei, imsi, android_id, mac, eth_mac, manu, model, tags

2.3 Parameter Combination Logic

• GroupIds and Keyword are AND relationship: filter by group first, then filter by keyword
• Date range StartDate to EndDate must be valid and not exceed 30 days

3. Outputs

3.1 Response Examples

Success response:

{
  "AppUsageDuration": {
    "has_data": "Data available",
    "apps": [
      {
        "pkg_id": "com.facebook.katana",
        "duration": 3600,
        "app_name": "Facebook",
        "icon_url": "https://example.com/icon.png"
      },
      {
        "pkg_id": "com.whatsapp",
        "duration": 2400,
        "app_name": "WhatsApp",
        "icon_url": "https://example.com/whatsapp.png"
      }
    ]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

No data response:

{
  "AppUsageDuration": {
    "has_data": "No data available",
    "apps": []
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

{
  "AppUsageDuration": {},
  "StatusCode": -1,
  "ErrorMessage": "Invalid start_date. Must be a non-empty string."
}

3.2 Field Descriptions

4. Examples

4.1 Basic Example: Query Last 7 Days App Usage Duration

Request parameters:

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03"
}

Response:

{
  "AppUsageDuration": {
    "has_data": "Data available",
    "apps": [
      {
        "pkg_id": "com.tencent.mm",
        "duration": 72000,
        "app_name": "WeChat",
        "icon_url": "https://cdn.example.com/wechat.png"
      },
      {
        "pkg_id": "com.alibaba.android.rimet",
        "duration": 54000,
        "app_name": "DingTalk",
        "icon_url": "https://cdn.example.com/dingtalk.png"
      }
    ]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Filter by Group and Keyword

Request parameters:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-31",
  "GroupIds": [100],
  "Keyword": "Sales"
}

4.3 Error Example: Date Format Error

Request parameters:

{
  "StartDate": "",
  "EndDate": "2026-01-31"
}

Response:

{
  "AppUsageDuration": {},
  "StatusCode": -1,
  "ErrorMessage": "Invalid start_date. Must be a non-empty string."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Set reasonable date ranges: Smaller date ranges mean faster queries
• Use group filtering: If only interested in specific groups, setting GroupIds reduces data volume
• Use keyword filtering: Use Keyword to precisely match target devices

6.2 Security Notes

🟢 Read operation: No special security requirements

6.3 Data Interpretation Tips

• duration unit is seconds; divide by 3600 to convert to hours
• has_data="No data available" means no data, possibly because:
  • Filter conditions are too strict
  • Devices have not reported data
  • No usage records within the date range

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 App Usage Analysis Pattern

Scenario: Comprehensive analysis of device app usage

Tool chain:

Get a Group ID by Group Name → Get Top 10 Apps by Usage Duration → Get Top 10 Data Usage Apps

Steps:

1. Call Get a Group ID by Group Name to get the target group's GroupId
2. Use GroupId to call Get Top 10 Apps by Usage Duration for app usage durations
3. Use the same parameters to call Get Top 10 Data Usage Apps for app data consumption
4. Compare and analyze the relationship between usage duration and data consumption

8.2 Device Efficiency Assessment Pattern

Scenario: Evaluate device work efficiency

Tool chain:

Get All Devices → Get Top 10 Apps by Usage Duration → Get Average Screen Time

Steps:

1. Call Get All Devices to get the device list
2. Use keyword filtering to call Get Top 10 Apps by Usage Duration for app usage data
3. Call Get Average Screen Time for screen usage time
4. Comprehensively analyze device usage efficiency