Get all devices

Tool Name: airdroid_business_get_devices

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

Summary: Retrieve a paginated list of AirDroid Business devices with optional single-field keyword filtering and field selection via SelectedColumns.

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,
  "Keyword": {}
}

Minimal Response Example (from publish):

{
  "Devices": [
    {
      "device_id": "ad0ea16dcb",
      "device_name": "Air 1",
      "note": "",
      "tags": [
        {
          "name": "Work 1",
          "tag_id": "1"
        }
      ]
    }
  ],
  "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,
  "Keyword": {}
}

Recipe 2: Keyword Filtering (Single Field)

When to use: Find all online Android devices in the "Chicago Warehouse" group.

{
  "SelectedColumns": ["device_id", "device_name", "online", "platform_type", "group_name"],
  "Page": 1,
  "PageSize": 50,
  "Keyword": {
    "online": "Online"
  }
}

Recipe 3: Pagination (Full Traversal)

When to use: Export all devices or enumerate devices before batch operations.

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

Pagination Key Point: Check Pagination.current_page and Pagination.last_page in the response. When current_page < last_page, set Page to current_page + 1 for the next request.

1. Overview

1.1 Description

Retrieve a paginated device list with support for:

• Single-field filtering via Keyword (one field at a time, fuzzy match)
• 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
• 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
• 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

Consistency Note: The publish RequestExample shows Keyword as an empty string "", but the DSL type is object and the code expects a dict. In the GI node, pass an empty object {} for "no filter".

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)
• Source: Not sourced from upstream; this controls which fields are returned
• How to fill in GI node:
  • Constant: Provide an array directly, e.g., ["device_id","device_name","online"]
  • Upstream reference: If upstream output is already an array type, map it directly (elements must be string field names)
• Example:

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

Why strongly recommended: Fewer fields mean smaller responses, lower cost for pagination traversal (less likely to hit token/network/timeout limits).

Consistency Note: The publish RequestExample.SelectedColumns includes "tag", but the DSL whitelist field is "tags" (plural). If you want to return tags, use "tags".

`Page`

• Type: number (code requires int)
• Format: Positive integer starting from 1
• How to fill in GI node:
  • Constant: 1
  • Upstream reference: For pagination loops, reference upstream Pagination.current_page and add 1
• Example:

1

`PageSize`

• Type: number (code requires int)
• Format: 1-50 (exceeding returns StatusCode=-1)
• How to fill in GI node:
  • Constant: 50
  • Upstream reference: Uncommon; recommend a fixed constant to avoid fluctuation
• Example:

50

`Keyword`

• Type: object
• Format: Native object (key-value). Only one field filter is supported at a time.
• Available values (excerpt, see appendix for full list):
  • Basic Info: device_name, group_name, note, tag
  • Status: online ("Offline"/"Online"), config_status, daemon_status ("Some not granted"/"All Granted"), am_state, lost_mode_status
  • Platform: platform_type ("Android"/"Windows"), model, manu
  • Network: network_type, signal_strength, ip, private_ip
  • Battery: battery (0-100), batterycharging, battery_source, battery_temperature
• Special Usage: Use key "all" to search across all supported fields, e.g., {"all": "Samsung"}
• Unsupported values:
  • group_id: Not supported; use group_name instead
• How to fill in GI node:
  • Constant: Provide an object directly, e.g., {"online":"Online"}
  • Upstream reference: If upstream output is an object, pass it directly (keys must be in the whitelist)
• Example:

{
  "device_name": "D one"
}

2.3 Parameter Combination Logic

• Keyword supports only one field filter at a time (except when using the "all" key)
• For multiple field filtering with AND logic, use Get All Devices With Filter instead
• SelectedColumns and Keyword can be used together: filter first, then return specified fields
• For no filtering: use an empty object Keyword: {} (do not use an empty string)

3. Outputs

3.1 Response Example (from publish)

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

3.2 Field Descriptions

3.3 Status Code / Enum Value Mapping (Excerpt)

Consistency Note: Some output fields may be numbers (e.g., online), while Keyword filter values are strings (e.g., "Online"). Use the DSL Keyword description for filter conditions; output field types follow actual responses.

3.4 Pagination Information

Pagination object structure (from DSL/publish):

total, page_size, current_page, last_page

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

4. Examples

4.1 Basic Example: Get First Page of Devices (Selected Fields)

Request Parameters:

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

Response (structure example, actual fields may vary):

{
  "Devices": [
    {
      "device_id": "ad0ea16dcb",
      "device_name": "Air 1",
      "online": 1,
      "battery": 85,
      "group_name": "Chicago Warehouse"
    }
  ],
  "Pagination": {
    "total": 100,
    "page_size": 50,
    "current_page": 1,
    "last_page": 2
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Filter by Group + Online Status

Request Parameters:

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

4.3 Error Example: PageSize Out of Range (Local Validation)

Request Parameters:

{
  "Page": 1,
  "PageSize": 100,
  "SelectedColumns": ["device_id", "device_name"],
  "Keyword": {}
}

Response (from code logic):

{
  "Devices": [],
  "Pagination": {},
  "StatusCode": -1,
  "ErrorMessage": "Invalid page_size, must be between 1 and 50."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

Core Principle: AB uses a three-layer error code strategy. The agent should decide handling based on StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Guide (Minimal Executable)

6. Best Practices

6.1 Performance Optimization

• Always specify SelectedColumns: Recommended ["device_id","device_name","online","battery","group_name"]
• Filter before paginating: Use Keyword to narrow the dataset, reducing full traversal cost
• 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 Online Devices (Example Chain)

Scenario: Reboot all online devices in the "Chicago Warehouse" group.

Tool Chain:

Get All Devices → Reboot Device

Steps:

1. Call Get All Devices:
   • Keyword={"online":"Online"}
   • SelectedColumns=["device_id","device_name","online","group_name"]
2. Iterate through Devices[] and pass each device_id to Reboot Device's DeviceId parameter

Appendix Reference:

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