Tool Name: airdroid_business_get_device_online_status_report
Risk Level: 🟢 Low Risk
Execution Mode: ⚡ Synchronous
Category: Reports & Analytics
Quick Start (Copy & Use)
In one sentence: Query device online/offline status and duration within a specified date range
What you need: StartDate (start date) + EndDate (end date)
Success criteria: StatusCode == 200 and ErrorMessage is empty; OnlineStatusList contains status data
What to do next: Analyze device online duration, generate availability reports, identify offline devices
Minimal request example:
{
"StartDate": "2026-01-01",
"EndDate": "2026-01-15"
}
Minimal response example:
{
"OnlineStatusList": [
{
"device_name": "Galaxy S24 - Sales Floor",
"group_name": "Retail - New York",
"model": "Samsung SM-S921U",
"online": "Online",
"duration": "12d 8h 45m",
"duration_min": 17685,
"start_date": "2026-01-01 00:00:00",
"end_date": "2026-01-15 23:59:59"
}
],
"Pagination": {
"total": 1,
"page_size": 10,
"current_page": 1,
"last_page": 1
},
"StatusCode": 200,
"ErrorMessage": ""
}
Recipes (Common Recipes)
Recipe 1: Query All Devices Online Status for the Last Two Weeks
Scenario: Generate device availability report
{
"StartDate": "2026-01-21",
"EndDate": "2026-02-03",
"Timezone": "America/New_York",
"Page": 1,
"PageSize": 50
}
Recipe 2: Filter by Device ID
Scenario: Query online status for a specific device
{
"StartDate": "2026-01-01",
"EndDate": "2026-01-31",
"DeviceIds": ["d8f3a2b1c4e5f6g7h8i9j0k1l2m3n4o5"],
"Timezone": "UTC",
"Page": 1,
"PageSize": 10
}
Recipe 3: Filter by Group
Scenario: Query online status for devices in specific groups
{
"StartDate": "2026-01-01",
"EndDate": "2026-01-31",
"GroupIds": [101, 102],
"Timezone": "America/New_York",
"Page": 1,
"PageSize": 50
}
1. Overview
1.1 Description
This tool queries device online/offline status reports within a specified date range, including the duration of online or offline periods. Suitable for device availability analysis, operations reports, and identifying long-term offline devices.
1.2 When to Use
- Availability analysis: Calculate device online duration and assess device availability
- Offline device identification: Find devices that have been offline for extended periods
- Operations reporting: Generate periodic reports on device online status
- Group comparison: Compare online status across different device groups
1.3 Execution Mode & Response
This is a synchronous operation that returns results immediately upon invocation.
- Return value: OnlineStatusList (online status list) + Pagination (pagination info)
- Timezone support: Timezone can be specified; returned times will display in the specified timezone
1.4 Prerequisites
| Condition | Description | How to Verify |
|---|---|---|
| Valid date range | StartDate and EndDate must be in correct format | Use YYYY-MM-DD format |
| EndDate >= StartDate | End date cannot be earlier than start date | Ensure date logic is correct |
| Account permission | Must have report viewing permissions | - |
1.5 Prerequisite Tools
| Dependency Tool | Purpose | Necessity |
|---|---|---|
| Get All Devices | Get DeviceIds for filtering | If filtering by device is needed |
| Get a Group ID by Group Name | Get GroupIds for filtering | If filtering by group is needed |
2. Inputs
2.1 Parameter List
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| StartDate | string | ✅ Yes | - | Report start date |
| EndDate | string | ✅ Yes | - | Report end date |
| Timezone | string | No | UTC | Timezone |
| Page | number | No | 1 | Current page number (min 1) |
| PageSize | number | No | 10 | Records per page (max 50) |
| DeviceIds | string-array | No | - | Device ID list |
| GroupIds | number-array | No | - | Group ID list |
2.2 Parameter Details
`Timezone`
Timezone setting for datetime conversion.
- Type: string
- Default: UTC
- Common values: UTC, America/New_York, America/Chicago, America/Los_Angeles, Europe/London
`DeviceIds` and `GroupIds`
- Combination logic: When both are provided, results are the union (OR relationship)
- Without either, returns data for all devices
3. Outputs
3.1 Response Examples
Success response:
{
"OnlineStatusList": [
{
"device_name": "Galaxy S24 - Sales Floor",
"group_name": "Retail - New York",
"model": "Samsung SM-S921U",
"online": "Online",
"duration": "12d 8h 45m",
"duration_min": 17685,
"start_date": "2026-01-01 00:00:00",
"end_date": "2026-01-15 23:59:59"
},
{
"device_name": "Pixel 8 Pro - Warehouse",
"group_name": "Logistics - Chicago",
"model": "Google Pixel 8 Pro",
"online": "Offline",
"duration": "2d 5h 30m",
"duration_min": 3210,
"start_date": "2026-01-01 00:00:00",
"end_date": "2026-01-15 23:59:59"
}
],
"Pagination": {
"total": 2,
"page_size": 10,
"current_page": 1,
"last_page": 1
},
"StatusCode": 200,
"ErrorMessage": ""
}
Error response:
{
"OnlineStatusList": [],
"Pagination": {},
"StatusCode": -1,
"ErrorMessage": "Invalid start_date. Must be a non-empty string."
}
3.2 Field Descriptions
| Field Path | Type | Description |
|---|---|---|
| StatusCode | number | Status code. See 5.1 AB Three-Layer Error Codes |
| ErrorMessage | string | Error message. Empty string on success |
| OnlineStatusList | array | Device online status list |
| OnlineStatusList[].device_name | string | Device display name |
| OnlineStatusList[].group_name | string | Device group name |
| OnlineStatusList[].model | string | Device model |
| OnlineStatusList[].online | string | Online status ("Online" or "Offline") |
| OnlineStatusList[].duration | string | Duration (format: Xd Xh Xm) |
| OnlineStatusList[].duration_min | number | Duration (in minutes) |
| OnlineStatusList[].start_date | string | Report period start time |
| OnlineStatusList[].end_date | string | Report period end time |
| Pagination | object | Pagination info object |
Tip: Use the duration_min field for numerical calculations
4. Examples
4.1 Basic Example: Query All Devices Online Status for Two Weeks
Request parameters:
{
"StartDate": "2026-01-01",
"EndDate": "2026-01-15",
"Timezone": "UTC",
"Page": 1,
"PageSize": 50
}
4.2 Advanced Example: Filter by Group with Local Timezone
Request parameters:
{
"StartDate": "2026-01-01",
"EndDate": "2026-01-31",
"Timezone": "America/New_York",
"GroupIds": [101, 102],
"Page": 1,
"PageSize": 20
}
4.3 Error Example: PageSize Exceeds Limit
Request parameters:
{
"StartDate": "2026-01-01",
"EndDate": "2026-01-15",
"PageSize": 100
}
Note: PageSize maximum is 50; exceeding it will be automatically capped at 50.
5. Error Handling
5.1 AB Three-Layer Error Codes
| StatusCode | Meaning | Usage Scenario | Agent Response |
|---|---|---|---|
| -1 | Parameter validation error | Local validation failed (missing required params, format errors) | ❌ Do not retry; fix parameters and call again |
| 200 | Business success or business error | HTTP request succeeded; check ErrorMessage | Empty ErrorMessage = success; non-empty = business error |
| 500 | Network/request exception | Timeout, connection failure, DNS resolution failure | ⚠️ May retry (up to 2 times, 5-second intervals) |
5.2 Common Errors
| StatusCode | ErrorMessage Example | Cause | Fix Suggestion |
|---|---|---|---|
| -1 | Invalid start_date. Must be a non-empty string. | Start date is empty | Provide a valid StartDate |
| -1 | Invalid end_date. Must be a non-empty string. | End date is empty | Provide a valid EndDate |
| -1 | access_token is invalid. | Auth token is invalid | Check credential configuration |
| 500 | Request timeout after 60 seconds. | Request timeout | Retry later |
5.3 Agent Self-Healing Decision Table
| StatusCode | Auto Retry | Retry Strategy | Manual Intervention |
|---|---|---|---|
| -1 | ❌ | - | Fix parameters and call again |
| 200 (non-empty ErrorMessage) | ❌ | - | Fix based on error message |
| 500 | ⚠️ | Up to 2 retries, 5-second intervals | Escalate if persistent failure |
6. Best Practices
6.1 Performance Optimization
- Use filter conditions: Narrow the query scope via DeviceIds or GroupIds
- Maximize PageSize: Use PageSize=50 to reduce request count
- Set reasonable date ranges: Avoid querying excessively long time spans
6.2 Security Notes
🟢 Read operation: This tool only queries status and has no special security requirements.
6.3 Timezone Usage Tips
- Report consistency: For team collaboration, recommend using UTC consistently
- Localized display: Use local timezone for end-user-facing reports
- Cross-timezone scenarios: Record original UTC time and convert when displaying
7. Related Tools
7.1 Prerequisite Tools
| Tool Name | Purpose |
|---|---|
| Get All Devices | Get DeviceIds for filtering |
| Get a Group ID by Group Name | Get GroupIds for filtering |
7.2 Follow-up Tools
| Tool Name | Purpose |
|---|---|
| Get All Devices | Get detailed info for offline devices |
| Get Device Info Push | Refresh device real-time status |
7.3 Similar Tools Comparison
| Tool Name | Use Case | Difference |
|---|---|---|
| Get All Devices | Real-time status query | Gets device current online status |
| Get Device Online Status Report | Historical status analysis | Queries online/offline duration statistics within a time period |
8. Tool Chains
8.1 Device Availability Report Pattern
Scenario: Generate device availability analysis report
Tool chain:
Get Device Online Status Report → Data analysis/export
Steps:
- Set date range and call Get Device Online Status Report
- Iterate through pages to get all records
- Use the duration_min field to calculate online rates
- Generate availability report
8.2 Offline Device Investigation Pattern
Scenario: Identify and address long-term offline devices
Tool chain:
Get Device Online Status Report → Get All Devices → Send notification
Steps:
- Call Get Device Online Status Report to get online status
- Filter records where online == "Offline" with high duration_min
- Use Get All Devices to get detailed info for those devices
- Notify the responsible personnel
8.3 Group Comparison Analysis Pattern
Scenario: Compare device online status across different groups
Tool chain:
Get a Group ID by Group Name (multiple groups) → Get Device Online Status Report (filter by group) → Comparative analysis
Steps:
- Use Get a Group ID by Group Name to get group IDs
- Call Get Device Online Status Report separately, filtering by GroupIds
- Compare average online duration across groups
Leave a Reply.