Get average screen time

Tool Name: airdroid_business_get_average_screen_time

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Reports & Analytics

Quick Start (Copy & Use)

In one sentence: Get average screen time trend data and overview statistics for devices

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

Success criteria: StatusCode=200 and ErrorMessage="" and ScreenTrendOverview contains overview_data and trend_data

What to do next: Analyze screen time trends, or combine with Get Top 10 Apps by Usage Duration to understand specific app usage

Minimal request example:

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

Minimal response example:

{
  "ScreenTrendOverview": {
    "overview_data": {
      "average_duration": 3500
    },
    "trend_data": [
      {
        "collect_date": "2026-01-01",
        "duration": 3500
      }
    ]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Query Last 30 Days Screen Time Trends

Scenario: Understand overall device screen usage trends

{
  "StartDate": "2026-01-05",
  "EndDate": "2026-02-03",
  "GroupIds": [0]
}

Recipe 2: Filter Screen Time by Group

Scenario: View screen 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 calculate screen time for Samsung devices

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

1. Overview

1.1 Description

Retrieve average screen time statistics for devices, including overview data (average for the date range) and daily trend data.

1.2 When to Use

• Usage trend analysis: Understand trends in device screen time changes
• Device management decisions: Evaluate device usage efficiency based on screen time
• Compliance monitoring: Monitor whether devices comply with usage policy requirements

1.3 Execution Mode & Response

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

• Return value: ScreenTrendOverview object containing overview statistics and trend data
• Data scope: Returns daily average screen time for the specified date range

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
• Example:

  "2026-01-01"

`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
• Example:

  "2026-01-31"

`DeviceIds`

• Type: string-array
• How to obtain:
  1. Via the Get All Devices tool — returns device_id in the Devices array
  2. Via the Get A Device By Name tool — for exact device name match
• Combination logic: When used with GroupIds, results are combined (OR/union)
• Example:

  ["fa6edcff65ab444e8b5e0eb08df4175d"]

`GroupIds`

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

  [100, 101]

`Keyword`

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

  "Samsung"

2.3 Parameter Combination Logic

• GroupIds and Keyword are AND relationship: filter by group first, then filter by keyword
• StartDate to EndDate determines the trend_data data range

3. Outputs

3.1 Response Examples

Success response:

{
  "ScreenTrendOverview": {
    "overview_data": {
      "average_duration": 9
    },
    "trend_data": [
      {
        "collect_date": "2025-12-23",
        "duration": 3500
      }
    ]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

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

3.2 Field Descriptions

3.3 Time Unit Notes

Important: All duration values are in seconds.

Conversion formulas:

• To minutes: duration / 60
• To hours: duration / 3600

4. Examples

4.1 Basic Example: Query Last 30 Days Screen Time Trends

Request parameters:

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

Response:

{
  "ScreenTrendOverview": {
    "overview_data": {
      "average_duration": 6500
    },
    "trend_data": [
      {
        "collect_date": "2026-01-05",
        "duration": 6200
      },
      {
        "collect_date": "2026-01-06",
        "duration": 6400
      }
    ]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Filter by Group

Request parameters:

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

4.3 Error Example: Missing Required Parameter

Request parameters:

{
  "StartDate": "2026-01-01"
}

Response:

{
  "ScreenTrendOverview": {},
  "StatusCode": -1,
  "ErrorMessage": "Invalid end_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 less returned data
• Use group filtering: If only interested in specific groups, setting GroupIds reduces data volume
• Correct date settings: Ensure dates are within the allowed 30-day range for accurate overview data

6.2 Security Notes

🟢 Read operation: No special security requirements

6.3 Data Interpretation Tips

• overview_data values are based on the specified date range
• trend_data duration values represent the daily per-device average
• If average_duration is 0, it may indicate no devices reported data during the period

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Device Usage Efficiency Analysis Pattern

Scenario: Comprehensive analysis of device usage efficiency

Tool chain:

Get Average Screen Time → Get Top 10 Apps by Usage Duration → Comparative analysis

Steps:

1. Call Get Average Screen Time to get screen usage trends
2. Call Get Top 10 Apps by Usage Duration to get app usage details
3. Compare and analyze the relationship between screen time and specific app usage

8.2 Group Efficiency Comparison Pattern

Scenario: Compare device usage across different groups

Tool chain:

Get a Group ID by Group Name (Group A) → Get Average Screen Time →
Get a Group ID by Group Name (Group B) → Get Average Screen Time → Comparative analysis

Steps:

1. Get Group A's GroupId and query screen usage time
2. Get Group B's GroupId and query screen usage time
3. Compare the usage trend differences between the two groups