Get all devices with filter

Tool Name: airdroid_business_get_devices_with_filter

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

Summary: Retrieve a paginated list of AirDroid Business devices with advanced Filter expressions supporting comparison operators and logical combinations.

Prerequisites: A valid OAuth2 AccessToken configured in the GI node Credential.

Success Criteria: StatusCode == 200 and ErrorMessage == "".

What to Do Next: Use Devices[].device_id as input for subsequent device action tools (e.g., Reboot Device, Lock a Device).

Minimal Request Example (recommended to copy directly):

{
  "SelectedColumns": ["device_name", "device_id", "note"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {}
}

Minimal Response Example (from publish):

{
  "Devices": [
    {
      "device_id": "ad0ea16dcb",
      "device_name": "Air 1",
      "note": ""
    }
  ],
  "Pagination": {
    "total": 100,
    "page_size": 50,
    "current_page": 1,
    "last_page": 2
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Minimal Field Set (Save Tokens)

When to use: For dashboards or inspections where you only need to identify devices along with online status, battery, and group.

{
  "SelectedColumns": ["device_id", "device_name", "online", "battery", "group_name"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {}
}

Recipe 2: Advanced Filter (Battery > 50%)

When to use: Filter for online devices with battery above 50%.

{
  "SelectedColumns": ["device_id", "device_name", "online", "battery"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {
    "online": 1,
    "battery": {"gt": 50}
  }
}

Recipe 3: Multi-Condition Combination

When to use: Filter for online devices with battery above 80%.

{
  "SelectedColumns": ["device_id", "device_name", "online", "battery", "batterycharging"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {
    "online": 1,
    "battery": {"gt": 80}
  }
}

Recipe 4: IN and BETWEEN Operators

When to use: Filter for Wi-Fi or Ethernet connected devices with battery between 20%-80%.

{
  "SelectedColumns": ["device_id", "device_name", "network_type", "battery"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {
    "network_type": {"in": [3, 4]},
    "battery": {"between": [20, 80]}
  }
}

Recipe 5: LIKE Fuzzy Match

When to use: Filter for devices with names containing "test" (case-insensitive).

{
  "SelectedColumns": ["device_id", "device_name", "online"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {
    "device_name": {"like": "test"}
  }
}

1. Overview

1.1 Description

Retrieve a paginated device list with support for:

• Advanced filtering via Filter (supports comparison operators and logical combinations)
• Field selection via SelectedColumns (reduce response size and token usage)

1.2 When to Use

• Pre-query for batch device operations: Fetch the device list first, then perform Reboot Device / Lock a Device on selected devices
• Complex condition filtering: When you need >, <, between, in and other operators
• Device inventory / export: Paginate through all devices and aggregate
• Status monitoring: Retrieve only online/battery status fields for quick dashboard data

1.3 Execution Mode and Response

This operation is synchronous and returns:

• Devices: Array of device objects
• Pagination: Pagination metadata (when using Filter, total reflects the filtered record count)
• StatusCode / ErrorMessage: Call status and error information

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Differences from Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`SelectedColumns`

• Type: string-array
• Format: String array (list of field names), max 10 items (DSL: MaxItems=10)
• Available values: See the field list in the DSL description (extensive list, see appendix)
• Example:

["device_id", "device_name", "online", "battery", "group_name"]

`Page`

• Type: number (code requires int)
• Format: Positive integer starting from 1
• Example:

1

`PageSize`

• Type: number (code requires int)
• Format: 1-50 (exceeding returns StatusCode=-1)
• Example:

50

`Filter`

• Type: object
• Format: Filter expression supporting operators and logical combinations
• Multiple conditions: Multiple fields listed together form an AND relationship
• Maximum conditions: 5

Supported Operators

Field Type and Operator Restrictions

Different field types support different operators:

If a field-operator combination is not supported, an error "Field 'xxx' does not support operator 'yyy'" will be returned.

Enum Field Values

Filter supports both numeric and string formats, consistent with Get All Devices Keyword parameter.

Example (the following two formats are equivalent):

• Numeric: {"online": 1, "network_type": {"in": [3, 4]}}
• String: {"online": "Online", "network_type": {"in": ["Wi-Fi", "Ethernet"]}}

Multi-Condition Queries

Multiple fields in the Filter form an AND relationship (all conditions must be met simultaneously).

• Example: Filter for online devices with battery above 80%

{
  "online": 1,
  "battery": {"gt": 80}
}

2.3 Parameter Combination Logic

• Multiple fields in Filter automatically form an AND relationship
• SelectedColumns and Filter can be used together: filter first, then return specified fields
• For no filtering: use an empty object Filter: {}

3. Outputs

3.1 Response Example

{
  "Devices": [
    {
      "device_id": "ad0ea16dcb",
      "device_name": "Air 1",
      "online": 1,
      "battery": 85,
      "batterycharging": 1
    },
    {
      "device_id": "bd1fb27edc",
      "device_name": "Air 2",
      "online": 1,
      "battery": 92,
      "batterycharging": 0
    }
  ],
  "Pagination": {
    "total": 15,
    "page_size": 50,
    "current_page": 1,
    "last_page": 1
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

3.2 Field Descriptions

3.3 Pagination Information

Pagination Strategy:

• When current_page < last_page, use Page = current_page + 1 for the next request
• Keep PageSize consistent to avoid missing or duplicating records during traversal

Note: When using the Filter parameter, Pagination.total reflects the filtered record count.

4. Examples

4.1 Basic Example: Get First Page (No Filter)

Request Parameters:

{
  "SelectedColumns": ["device_id", "device_name", "online", "battery", "group_name"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {}
}

4.2 Advanced Example: Filter for High Battery Devices

Request Parameters:

{
  "SelectedColumns": ["device_id", "device_name", "online", "battery"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {
    "online": 1,
    "battery": {"gte": 80}
  }
}

4.3 Advanced Example: Multi-Condition Combination

Scenario: Filter for online devices with battery below 20%.

Request Parameters:

{
  "SelectedColumns": ["device_id", "device_name", "online", "battery", "last_connect_date"],
  "Page": 1,
  "PageSize": 50,
  "Filter": {
    "online": 1,
    "battery": {"lt": 20}
  }
}

4.4 Error Example: Exceeding Maximum Conditions

Request Parameters (error):

{
  "Filter": {
    "online": 1,
    "battery": {"gt": 50},
    "cpu_usage": {"lt": 80},
    "network_type": 3,
    "device_name": {"like": "test"},
    "model": "Samsung"
  }
}

Note: Filter supports a maximum of 5 conditions; exceeding this returns an error.

Response:

{
  "Devices": [],
  "Pagination": {},
  "StatusCode": -1,
  "ErrorMessage": "Filter conditions exceeded (max: 5, got: 6)"
}

5. Error Handling

5.1 Common Errors

5.2 Agent Self-Healing Guide

6. Best Practices

6.1 Performance Optimization

• Always specify SelectedColumns: Recommended ["device_id","device_name","online","battery","group_name"]
• Use Filter wisely: Complex Filter expressions may impact performance
• Keep PageSize stable: Maintain consistency during traversal to reduce duplication/omission risk

6.2 Security Considerations

This action is a read operation, but returned fields may contain sensitive information (e.g., SIM/phone/location fields). It is recommended not to retrieve these by default; add them to SelectedColumns only when business needs require it.

6.3 Idempotency

This is a read operation and is naturally idempotent. However, device status is dynamic, so the same parameters may yield different results on repeated calls.

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tool Comparison

8. Tool Chains

8.1 Batch Reboot Low-Battery Online Devices

Scenario: Reboot all online devices with battery below 20%.

Tool Chain:

Get All Devices With Filter → Reboot Device

Steps:

1. Call Get All Devices With Filter:
   • Filter={"online": 1, "battery": {"lt": 20}} (multiple fields listed directly, default AND relationship)
   • SelectedColumns=["device_id","device_name","battery"]
2. Iterate through Devices[] and pass each device_id to Reboot Device's DeviceId parameter

8.2 Filter by Network Type and Set Tags

Scenario: Add a "Stable Network" tag to all devices connected via Wi-Fi or Ethernet.

Tool Chain:

Get All Devices With Filter → Set Tags

Steps:

1. Call Get All Devices With Filter:
   • Filter={"network_type": {"in": [3, 4]}} (3=Wi-Fi, 4=Ethernet)
   • SelectedColumns=["device_id","device_name","network_type"]
2. Iterate through Devices[] and call Set Tags for each device

Appendix Reference:

• Field Reference: https://www.goinsight.ai/tools/field-reference/
• Error Code Quick Reference: https://www.goinsight.ai/tools/error-codes/