Tools

Search Groups

Tool Name: airdroid_business_group_search

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Group Management

Quick Start (Copy & Use)

Summary: Retrieve a paginated list of AirDroid Business groups with server-side Filter expressions. Pagination.total always reflects the filtered count.

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

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

What to Do Next: Use Groups[].id as GroupId for subsequent group or device operations.

Minimal Request Example (recommended to copy directly):

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {}
}

Minimal Response Example:

{
  "Groups": [
    {
      "id": 123,
      "name": "Sales",
      "parent_group_id": 0,
      "remark": "",
      "deploy_code": "ABC123",
      "create_date": "2024-01-15 10:30:00",
      "is_default": "No",
      "is_leaf": "Yes",
      "level": 1,
      "max_child_depth": 0,
      "num": 5,
      "num_sg": 5,
      "path": ["Sales"]
    }
  ],
  "Pagination": {
    "total": 1,
    "page_size": 50,
    "page_index": 1,
    "last_page": 1
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Get All Top-Level Groups

When to use: List all groups at the root level (no parent).

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "parent_group_id": 0
  }
}

Recipe 2: Find Groups by Name

When to use: Search for groups whose name contains a keyword.

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "name": {"like": "Sales"}
  }
}

Recipe 3: Get the Default Group

When to use: Find the system default group (devices not assigned to any group land here).

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "name": "Default"
  }
}

Recipe 4: Find Groups Created After a Date

When to use: Audit newly created groups since a specific date.

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "create_date": {"gte": "2024-01-01 00:00:00"}
  }
}

Recipe 5: Find a Group by Exact Name and Get Its ID

When to use: Resolve a group name to its id before moving devices or creating sub-groups.

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "name": "Sales Department"
  }
}

1. Overview

1.1 Description

Retrieve a paginated group list with support for:

Server-side filtering via Filter (supports comparison operators and logical combinations)
Pagination.total always reflects the filtered count, not the total group count

1.2 When to Use

Resolve group name → id: Filter by name to get id before device moves or sub-group creation
Inspect group hierarchy: Filter by parent_group_id to list children of a specific group
Audit groups: Filter by create_date to find recently created groups
Find the Default Group: Use {"name": "Default"} to locate the system default group

1.3 Execution Mode and Response

This operation is synchronous and returns:

Groups: Array of group objects
Pagination: Pagination metadata (total reflects the filtered count)
StatusCode / ErrorMessage: Call status and error information

1.4 Prerequisites

Condition	Description	How to Check
Valid credential	A valid OAuth2 AccessToken is required	Configure AirDroid Business OAuth2 credential in the GI node

1.5 Differences from Similar Tools

Tool	Use Case	Key Difference
Search Groups	Complex condition filtering, comparison operators	Supports Filter with eq/ne/gt/gte/lt/lte/in/like/between operators and $or
Get a Group	Single group lookup by ID	Returns one group including its sub-group list
Resolve Group ID by Name	Exact name → ID lookup	Only exact name match; no pagination

2. Inputs

2.1 Parameter List

Parameter	Type	Required	Default	Description
PageIndex	number	No	1	Page index (1-based), starting from 1
PageSize	number	No	50	Records per page, range 1-50
Filter	object	No	{}	Server-side filter expression

2.2 Parameter Details

`PageIndex`

Type: number
Format: Positive integer starting from 1
Example: 1

`PageSize`

Type: number
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 field conditions (excluding $or)

Supported Operators

Operator	Description	Example
eq	Equals	{"name": "Sales"}
ne	Not equals	{"name": {"ne": "Default"}}
gt	Greater than	{"create_date": {"gt": "2024-01-01 00:00:00"}}
gte	Greater than or equals	{"create_date": {"gte": "2024-01-01 00:00:00"}}
lt	Less than	{"create_date": {"lt": "2025-01-01 00:00:00"}}
lte	Less than or equals	{"create_date": {"lte": "2025-01-01 00:00:00"}}
in	Value in array	{"id": {"in": [10, 20, 30]}}
like	Fuzzy match (contains)	{"name": {"like": "Sales"}}
between	Range	{"create_date": {"between": ["2024-01-01 00:00:00", "2024-12-31 23:59:59"]}}

Filterable Fields

All fields below accept any of the operators above.

Field	Aliases	Notes
id	group_id	Unique group identifier; prefer id
parent_group_id	—	0 = top-level group
name	group_name	Default group always has name = "Default"; prefer name
remark	—	Group notes/remarks
create_date	—	Format: "YYYY-MM-DD HH:MM:SS"
path	—	Group hierarchy path segments (matched against full path)

Using any field outside this list returns an error.

Multi-Condition Queries

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

Example: Groups at the root level created after 2024-01-01

{
  "parent_group_id": 0,
  "create_date": {"gte": "2024-01-01 00:00:00"}
}

OR Queries with `$or`

$or provides one-level OR logic — nested $or is not supported. It must contain at least 2 items, and each item must contain exactly one field condition. $or does not count toward the 5-condition limit.

Example: Name contains 'A' OR 'B'

{
  "$or": [{"name": {"like": "A"}}, {"name": {"like": "B"}}]
}

Example: Top-level AND (name OR remark contains 'Sales')

{
  "parent_group_id": 0,
  "$or": [{"name": {"like": "Sales"}}, {"remark": {"like": "Sales"}}]
}

3. Outputs

3.1 Response Example

{
  "Groups": [
    {
      "id": 123,
      "name": "Sales",
      "parent_group_id": 0,
      "remark": "Sales team devices",
      "deploy_code": "ABC123",
      "create_date": "2024-01-15 10:30:00",
      "is_default": "No",
      "is_leaf": "No",
      "level": 1,
      "max_child_depth": 2,
      "num": 5,
      "num_sg": 20,
      "path": ["Sales"]
    },
    {
      "id": 456,
      "name": "North",
      "parent_group_id": 123,
      "remark": "",
      "deploy_code": "DEF456",
      "create_date": "2024-03-10 08:00:00",
      "is_default": "No",
      "is_leaf": "Yes",
      "level": 2,
      "max_child_depth": 0,
      "num": 15,
      "num_sg": 15,
      "path": ["Sales", "North"]
    }
  ],
  "Pagination": {
    "total": 2,
    "page_size": 50,
    "page_index": 1,
    "last_page": 1
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

3.2 Field Descriptions

Field Path	Type	Description
Groups	object-array	Array of group objects for the current page
Groups[].id	number	Unique group identifier
Groups[].name	string	Group display name; the default group always returns "Default"
Groups[].parent_group_id	number	Parent group ID; 0 = top-level group
Groups[].remark	string	Group notes/remarks
Groups[].deploy_code	string	Group deployment code
Groups[].create_date	string	Creation time, format "YYYY-MM-DD HH:MM:SS"
Groups[].is_default	string	"Yes" = system default group; "No" = normal group
Groups[].is_leaf	string	"Yes" = no sub-groups; "No" = has sub-groups
Groups[].level	number	Nesting depth (1 = top-level)
Groups[].max_child_depth	number	Maximum sub-group depth under this group
Groups[].num	number	Direct device count
Groups[].num_sg	number	Total device count including sub-groups
Groups[].path	array	Full hierarchy path from root to this group, e.g. ["Sales", "North"]; each element is a group name segment
Pagination.total	number	Total filtered group count
Pagination.page_size	number	Records per page
Pagination.page_index	number	Current page index (1-based)
Pagination.last_page	number	Last page number
StatusCode	number	200 = success, -1 = parameter error, 500 = exception
ErrorMessage	string	Empty on success; error description on failure
Hint	string	Next-action guidance on error; empty on success
Retryable	boolean	true = transient error; false = persistent error or bad params
OriginalStatusCode	number	Upstream HTTP status code; 0 = no upstream response

3.3 Pagination

When page_index < last_page, use PageIndex = page_index + 1 for the next page
Pagination.total always reflects the filtered group count

4. Examples

4.1 Basic: List Groups (No Filter)

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {}
}

4.2 Get Top-Level Groups

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "parent_group_id": 0
  }
}

4.3 Find Groups by Name Keyword

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "name": {"like": "Sales"}
  }
}

4.4 Get the Default Group

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "name": "Default"
  }
}

4.5 Find Groups by ID List

{
  "PageIndex": 1,
  "PageSize": 50,
  "Filter": {
    "id": {"in": [10, 20, 30]}
  }
}

4.6 Error: Unsupported Filter Field

Request (error):

{
  "Filter": {
    "is_default": 1
  }
}

Response:

{
  "Groups": [],
  "Pagination": {},
  "StatusCode": -1,
  "ErrorMessage": "Unsupported filter field: is_default.",
  "Hint": "Use supported group filter fields and operators, then retry."
}

5. Error Handling

5.1 Common Errors

StatusCode	Cause	Fix
-1	Invalid credential / empty token	Configure AirDroid Business OAuth2 Credential
-1	PageSize out of range (>50 or <1)	Change to 1-50
-1	Unsupported filter field	Use only: id (group_id), parent_group_id, name (group_name), remark, create_date, path
-1	More than 5 filter conditions (excluding $or)	Reduce to ≤ 5 field conditions
-1	Invalid JSON for Filter	Ensure Filter is a valid JSON object
500	Network or server timeout	Retry up to 2 times

5.2 Agent Self-Healing Guide

Condition	Handling Strategy
StatusCode == 200 and ErrorMessage == ""	Success, read Groups and Pagination
StatusCode == 200 and ErrorMessage != ""	Business error; check Hint for guidance
StatusCode == -1	Fix input parameters or Credential and retry
StatusCode == 500	Retry up to 2 times (5-second interval); escalate if persistent

6. Best Practices

Filter before paginating: Use Filter to narrow down results before paginating through all pages
Default group: Always returned with name = "Default" and is_default = "Yes"
Resolve name → id: Use {"name": "exact name"} with eq to get the group id before performing write operations
Full path: Use path to display the complete group hierarchy (e.g. ["Sales", "North"])

7. Related Tools

7.1 Follow-up Tools

Tool Name	Purpose
Get a Group	Get full details of a single group including its sub-group list
Create a Group	Create a new group (use id as ParentGroupId)
Update a Group Name	Rename a group (use id as GroupId)
Update a Group Remark	Update group remark (use id as GroupId)
Delete Groups	Delete groups (use id as input)
Move Devices to a Group	Move devices into a group (use id as GroupId)

7.2 Similar Tool Comparison

Tool	Use Case	Difference
Search Groups	List / search groups with conditions	Supports multi-field server-side filtering
Get a Group	Single group detail	Returns sub-group list; requires exact GroupId
Resolve Group ID by Name	Exact name → ID lookup	Exact match only; no pagination

8. Tool Chains

8.1 Find a Group and Move Devices Into It

Scenario: Move all devices in a known group into a new group found by name.

Tool Chain:

Search Groups → Move Devices to a Group

Steps:

Call Search Groups with Filter = {"name": {"like": "New Region"}}
Take Groups[0].id as the target GroupId
Call Move Devices to a Group with the resolved GroupId

8.2 Audit Recently Created Groups

Scenario: List all groups created in the last 30 days.