Get device network connection history

Tool Name: airdroid_business_get_device_network_connection_history

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Reports & Analytics

Quick Start (Copy & Use)

In one sentence: Get device network connection history, including WiFi/mobile data/Ethernet usage percentages and primary network info

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

Success criteria: StatusCode=200 and ErrorMessage="" and NetworkHistoryList contains data

What to do next: Analyze device network usage, or paginate to get more data

Minimal request example:

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

Minimal response example:

{
  "NetworkHistoryList": [
    {
      "device_id": "abc123",
      "device_name": "Device A",
      "group_name": "Sales",
      "group_id": 100,
      "connection_time": "95%",
      "wifi_percent": "70%",
      "gsm_percent": "20%",
      "ethernet_percent": "10%",
      "main_wifi": "Office_WiFi",
      "main_gsm": "China Mobile"
    }
  ],
  "Pagination": {
    "total": 50,
    "page_size": 10,
    "current_page": 1,
    "last_page": 5
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Query Last 7 Days Network History for All Devices

Scenario: Understand overall device network connection status

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03",
  "Page": 1,
  "PageSize": 10,
  "Ascending": true
}

Recipe 2: Filter Network History by Group

Scenario: View network history for specific groups only

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03",
  "GroupIds": [100, 101],
  "Page": 1,
  "PageSize": 10
}

Recipe 3: Query by Device ID

Scenario: Query network connection history for a specific device

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03",
  "DeviceIds": ["abc123def456ghi789"],
  "Page": 1,
  "PageSize": 10
}

Recipe 4: Search by Keyword

Scenario: Fuzzy search for devices matching a keyword

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03",
  "Keyword": "Samsung",
  "Page": 1,
  "PageSize": 10
}

Recipe 5: Get Extra Fields

Scenario: Need device IMEI, model, and other extra info

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03",
  "SelectedColumns": ["snid", "model", "imei", "mac", "tags"],
  "Page": 1,
  "PageSize": 10
}

1. Overview

1.1 Description

Get device network connection history within a specified date range, including WiFi, mobile data, and Ethernet usage percentages, as well as primary connected network names.

1.2 When to Use

• Network usage analysis: Understand which network type devices use most
• Connection quality assessment: Evaluate network connection quality via signal strength
• Cost optimization: Analyze WiFi vs. mobile data usage ratios
• Troubleshooting: Check device network connection history to diagnose issues

1.3 Execution Mode & Response

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

• Return value: NetworkHistoryList array + Pagination pagination info
• Pagination support: Controlled via Page/PageSize parameters

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`StartDate` and `EndDate`

• Type: string
• Format: YYYY-MM-DD (e.g., 2026-01-28)
• Constraints:
  • Cannot query data older than 7 days
  • Cannot be future dates
  • Date range cannot exceed 7 days

`SelectedColumns`

• Type: string-array
• Purpose: Specify extra fields to return
• Options: snid, model, android_id, imsi, imei, mac, eth_mac, tags, manu
• Default fields (no need to specify): device_name, note, group_name, group_id, connection_time, wifi_percent, gsm_percent, ethernet_percent, main_wifi, main_gsm, wifi_strength, gsm_strength, ethernet_strength
• Example:

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

`Ascending`

• Type: bool
• Description: Sort by device name. true = ascending (A to Z), false = descending (Z to A)
• Default: true

`DeviceIds` and `GroupIds`

• Combination logic: DeviceIds and GroupIds are OR (union) — results from both are merged
• Keyword is AND with the above filters

3. Outputs

3.1 Response Examples

Success response:

{
  "NetworkHistoryList": [
    {
      "device_id": "abc123",
      "device_name": "Device A",
      "group_name": "Sales",
      "group_id": 100,
      "connection_time": "95%",
      "wifi_percent": "70%",
      "gsm_percent": "20%",
      "ethernet_percent": "10%",
      "main_wifi": "Office_WiFi",
      "main_gsm": "China Mobile",
      "wifi_strength": "Excellent",
      "gsm_strength": "Good",
      "ethernet_strength": "No signal",
      "note": "Office device",
      "model": "SM-G9500",
      "mac": "AA:BB:CC:DD:EE:FF",
      "snid": "SN12345"
    }
  ],
  "Pagination": {
    "total": 50,
    "page_size": 10,
    "current_page": 1,
    "last_page": 5
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

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

3.2 Field Descriptions

NetworkHistoryList fields (default):

NetworkHistoryList fields (via SelectedColumns):

4. Examples

4.1 Basic Example: Query Last 7 Days Network History

Request parameters:

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03",
  "Page": 1,
  "PageSize": 10
}

4.2 Advanced Example: Filter by Group with Extra Fields

Request parameters:

{
  "StartDate": "2026-01-28",
  "EndDate": "2026-02-03",
  "GroupIds": [100],
  "SelectedColumns": ["model", "imei", "mac"],
  "Page": 1,
  "PageSize": 20
}

4.3 Error Example: Date Range Exceeds Limit

Request parameters:

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

Response:

{
  "NetworkHistoryList": [],
  "Pagination": {},
  "StatusCode": 200,
  "ErrorMessage": "Date range exceeds 7 days limit"
}

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: Set DeviceIds or GroupIds to reduce returned data volume
• Set reasonable PageSize: Recommend 10-20 to avoid returning too much data at once
• Request only needed fields: Use SelectedColumns to request only the extra fields you need

6.2 Security Notes

🟢 Read operation: No special security requirements

6.3 Data Interpretation Tips

• connection_time represents the device's total online rate
• wifi_percent + gsm_percent + ethernet_percent may not equal 100% (offline time exists)
• main_wifi and main_gsm are the networks with the longest usage time

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Network Quality Analysis Pattern

Scenario: Analyze device network quality for a specific group

Tool chain:

Get a Group ID by Group Name → Get Device Network Connection History → Analyze wifi_strength/gsm_strength

Steps:

1. Get the target group's GroupId
2. Call this tool to get network connection history
3. Analyze wifi_strength and gsm_strength to assess network quality

8.2 Data Cost Optimization Pattern

Scenario: Identify devices with high mobile data usage

Tool chain:

Get Device Network Connection History → Filter devices with high gsm_percent → Get Data Usage Overview and Trends

Steps:

1. Call this tool to get all device network connection history
2. Filter devices with high gsm_percent
3. Call the data usage statistics tool to get specific data consumption
4. Develop optimization strategies (e.g., increase WiFi coverage)