Get device application usage duration

Tool Name: airdroid_business_get_device_application_usage_duration

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Reports & Analytics

Quick Start (Copy & Use)

In one sentence: Query device app usage duration statistics for a specified date range

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

Success criteria: StatusCode == 200 and ErrorMessage is empty; DeviceUsageDurationList contains usage data

What to do next: Analyze app usage patterns, generate usage reports, identify usage anomalies

Minimal request example:

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

Minimal response example:

{
  "DeviceUsageDurationList": [
    {
      "device_id": "abc123",
      "device_name": "Device A",
      "group_name": "Sales",
      "group_id": 100,
      "duration": 7200,
      "device_data_status": "Normal, has data",
      "pkg_info": [
        {
          "pkg_id": "com.tencent.mm",
          "app_name": "WeChat",
          "icon_url": "https://example.com/wechat.png",
          "duration": 3600
        }
      ]
    }
  ],
  "Pagination": {
    "total": 50,
    "page_size": 10,
    "current_page": 1,
    "last_page": 5
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Query All Devices Usage Duration for the Last Week

Scenario: Generate weekly usage report

{
  "StartDate": "2026-01-27",
  "EndDate": "2026-02-03",
  "Page": 1,
  "PageSize": 50
}

Recipe 2: Query Usage Duration by Group

Scenario: View app usage for a specific group's devices

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-28",
  "GroupIds": [100],
  "Page": 1,
  "PageSize": 20
}

Recipe 3: Search for Specific Device with Extra Fields

Scenario: Find usage details for a specific device

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-28",
  "Keyword": "Samsung",
  "SelectedColumns": ["model", "imei", "os_version"],
  "Page": 1,
  "PageSize": 10
}

Recipe 4: Paginate Through All Records

Scenario: Paginate when there are many devices

Paging strategy:

• First request with Page=1, get Pagination.last_page
• When current_page < last_page, use Page + 1 to get the next page

1. Overview

1.1 Description

This tool queries device app usage duration statistics for a specified date range. It returns the total usage duration for each device and the Top 5 apps by usage time. Suitable for productivity analysis, device usage monitoring, app usage compliance checks, and similar scenarios.

1.2 When to Use

• Productivity analysis: Understand device usage time distribution
• App usage monitoring: See which apps consume the most time
• Compliance checks: Ensure devices are used for work-related apps
• Device utilization analysis: Identify low-usage devices

1.3 Execution Mode & Response

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

• Return value: DeviceUsageDurationList (usage duration list) + Pagination (pagination info)
• Data scope: Returns Top 5 apps by usage time for each device

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`StartDate`

Query start date.

• Type: string
• Format: YYYY-MM-DD
• Constraints:
  • Cannot be a future date
  • Cannot query data older than 30 days
• Example:

  "2026-01-01"

`EndDate`

Query end date.

• Type: string
• Format: YYYY-MM-DD
• Constraints:
  • Cannot be earlier than StartDate
  • Cannot be a future date
  • Interval with StartDate cannot exceed 30 days
• Example:

  "2026-01-28"

`SelectedColumns`

Extra device info fields to return.

• Type: string-array
• Default fields (always included):
  • device_name, snid, group_name, group_id, tags
  • duration (seconds), pkg_info (Top 5 apps), device_data_status
• Optional fields:
  • model: Device model
  • android_id: Android device ID
  • imsi: Primary IMSI number
  • imei: Primary IMEI number
  • mac: WiFi MAC address
  • hdmi: HDMI info
  • eth_mac: Ethernet MAC address
  • app_version_open: App version
  • iccid1: SIM card ICCID
  • phone_number1: Phone number
  • os_version: OS version
  • manu: Manufacturer
  • ip: Public IP
  • private_ip: Private IP
• Example:

  ["model", "imei", "mac"]

`GroupIds`

Group ID list for filtering specific group devices.

• Type: number-array
• How to obtain:
  1. Via the Get a Group ID by Group Name tool
  2. Via the Get All Devices tool — group_id field in results
• Combination logic: When used with DeviceIds, results are combined (OR/union)
• Example:

  [100, 101]

`Keyword`

Search keyword for fuzzy matching device information.

• Type: string
• Searchable fields: device_id, device_name, group_name, note, snid, imei, imsi, mac, eth_mac, manu, model, android_id, tags, os_version, app_version
• Example:

  "Samsung"

2.3 Parameter Combination Logic

• StartDate and EndDate must both be provided, with interval not exceeding 30 days
• GroupIds and Keyword can be used independently or combined
• SelectedColumns only affects returned fields, not filtering logic

3. Outputs

3.1 Response Examples

Success response:

{
  "DeviceUsageDurationList": [
    {
      "device_id": "abc123",
      "device_name": "Device A",
      "group_name": "Sales",
      "group_id": "100",
      "snid": "SN123456",
      "tags": [{"tag_id": 1, "name": "VIP"}],
      "duration": 7200,
      "device_data_status": "Normal, has data",
      "pkg_info": [
        {
          "pkg_id": "com.tencent.mm",
          "app_name": "WeChat",
          "icon_url": "https://example.com/wechat.png",
          "duration": 3600
        },
        {
          "pkg_id": "com.whatsapp",
          "app_name": "WhatsApp",
          "icon_url": "https://example.com/whatsapp.png",
          "duration": 1800
        }
      ]
    }
  ],
  "Pagination": {
    "total": 50,
    "page_size": 10,
    "current_page": 1,
    "last_page": 5
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

{
  "DeviceUsageDurationList": [],
  "Pagination": {},
  "StatusCode": -1,
  "ErrorMessage": "Invalid start_date. Must be a non-empty string."
}

3.2 Field Descriptions

3.3 device_data_status Values (Important)

Important: When device_data_status is not "Normal, has data", duration may be 0 or inaccurate, and pkg_info may be empty. Verify data validity based on the status.

3.4 Duration Unit

Conversion:

• Minutes = duration / 60
• Hours = duration / 3600

4. Examples

4.1 Basic Example: Query All Devices Usage for One Week

Request parameters:

{
  "StartDate": "2026-01-20",
  "EndDate": "2026-01-27",
  "Page": 1,
  "PageSize": 20
}

4.2 Advanced Example: Query by Group with Device Model

Request parameters:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-28",
  "GroupIds": [100],
  "SelectedColumns": ["model", "os_version"],
  "Page": 1,
  "PageSize": 10
}

4.3 Error Example: Date Range Exceeds 30 Days

Request parameters:

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

Note: Date range is limited to 30 days. Exceeding may return an error or be automatically truncated. Consider querying in segments.

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

• Use filter conditions: Use GroupIds or Keyword to narrow the query scope
• Increase PageSize: Set a larger PageSize as needed to reduce request count
• Control date range: Smaller query ranges yield faster responses

6.2 Security Notes

🟢 Read operation: This tool only queries usage data and has no special security requirements.

Privacy note: App usage duration may involve employee privacy; ensure appropriate usage policies and access controls are in place.

6.3 Data Validity Checks

When processing returned data, always check device_data_status:

if device_data_status == "Normal, has data":
    # Data is valid; duration and pkg_info can be used
elif device_data_status contains "Android system version too low":
    # Android version too low; cannot collect data
elif device_data_status contains "Daemon version too low":
    # Daemon version too low; needs update
elif device_data_status contains "AMS permission not enabled":
    # AMS permission not enabled; needs authorization on device
elif device_data_status contains "Device offline":
    # Device offline or no data transmitted

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Productivity Analysis Pattern

Scenario: Analyze employee device usage

Tool chain:

Get Device Application Usage Duration → Data analysis/visualization

Steps:

1. Set date range and call the tool to get usage data
2. Filter valid data where device_data_status == "Normal, has data"
3. Aggregate duration to generate usage duration rankings
4. Analyze app usage distribution in pkg_info

8.2 Group Usage Comparison Pattern

Scenario: Compare device usage across different departments

Tool chain:

Get a Group ID by Group Name (multiple groups) → Get Device Application Usage Duration (query by group) → Comparative analysis

Steps:

1. Use Get a Group ID by Group Name to get GroupIds for each department
2. Call the tool separately, filtering by GroupIds
3. Calculate average usage duration per group
4. Compare and analyze usage differences across departments

8.3 Usage Anomaly Detection Pattern

Scenario: Identify devices with abnormal usage durations

Tool chain:

Get Device Application Usage Duration → Anomaly detection → Get All Devices → Notification

Steps:

1. Get usage durations for all devices
2. Calculate mean and standard deviation to identify anomalies (too high or too low)
3. Use Get All Devices to get detailed info for anomalous devices
4. Notify responsible personnel for investigation