# avatar_groups

Returns a list of a resident’s Second Life groups.

```csharp
// See "LSL Helper Functions" page for this function
smartbotsAPI("avatar_groups", [
  "avatar", "cd93067e-7c4e-41c0-ba91-be01f4bafe35"
]);
```

# Variables

The following table shows input values (you send them with the API call) and returned output values.


:::info
**Note:** This API command applies only to **Standard bots**.

:::

## Input basic parameters

| Variable | Required | Description |
|----------|----------|-------------|
| action   | yes      | = avatar_groups |
| apikey   | yes      | Your personal [developer's API key](/doc/developers-api-key-tw8bQj4LSJ) |
| botname  | yes      | Your bot’s SL login |
| secret   | yes      | [Bot access code](https://www.mysmartbots.com/docs/Bot_access_code) of your bot |
| dataType | optional | Set to `"json"` to get JSON reply instead of URL-encoded string |
| custom   | optional | The custom data (string) to be passed back to the caller script. This value will be returned in the HTTP response |

## Input

| Variable | Required | Description |
|----------|----------|-------------|
| avatar   | yes      | The UUID of the avatar whose groups to fetch |
| skipnames | optional | Skip groups whose names **contain** this substring (case-insensitive) |
| matchnames | optional | Return only groups whose names **contain** this substring (case-insensitive) |
| matchuuid | optional | Return only the group with this specific UUID |

## Output

*(To be received in* `http_response` *LSL event, see* [*docs for details*](/doc/doing-http-api-calls-c6FSEMF7bP)*)*

| Variable | Description |
|----------|-------------|
| result   | `OK`- command completed successfully<br>`FAIL` - command failed |
| resulttext | Detailed reason for the failure |
| custom   | The value from input `"custom"` parameter |
| total    | The total number of resident’s groups (not affected by filters) |
| groups   | The list of groups (filtered if `skip*` or `match*` parameters used). Contains UUIDs and group names separated by newline (`\n`) |

### Example Output Format

```
UUID1 Group Name 1
UUID2 Group Name 2
...
```


---

# Usage Comments

### Working with large lists

The **LSL** `**llHTTPRequest()**` function limits response size to **2048 bytes (1024 Unicode characters)**.  
If the resident has many groups, use filters to reduce output size:

* `skipnames` — ignore groups containing this substring
* `matchnames` — include only groups containing this substring
* `matchuuid` — return a specific group by UUID

### Limits

This command is rate-limited due to Second Life asset server load:  
**Maximum 5 requests per 30 seconds.**


---

# Examples

### Example 1 — Get all groups

```
https://www.mysmartbots.com/api/bot.html?action=avatar_groups&botname=BarKeeeper%20Resident&avatar=cd93067e-7c4e-41c0-ba91-be01f4bafe35
```

**Response:**

```
0b4a7c17-4e2b-bc96-34c1-4cb6e67a9fd2 SLBiz2Life - Advertisers Support
0b65a122-8f77-64fe-5b2a-225d4c490d9c SmartBots: group invitation bots
0e6ce87d-d86e-9225-9e0f-cea9fb24313e Capital Exchange Stock Market
0ec6f039-1a39-339c-3c68-e31ed2dc703f Earn2Life.com Discount Shops
24dcd8e6-3406-1518-b9ba-8653c1be09eb Earn2Life.com partnership
41ff4c6b-e3c0-a2b9-f53b-797e78532374 Earn2Life - earn L$500-1000 a day
4fbbee90-b278-e1b9-0ec9-251da2390c6c Earn2Life.com Investors (EARN)
5c63bbff-7064-0849-e8a7-25dff3d1765f Earn2Life.com Training Group
9e325390-c5e0-de09-3921-1501d34f9b38 Earn2Life Pay4Observe Support
c63983a8-f9b6-cb4b-6cdd-87da2f679a8e SmartBots Investors (BOTS)
cee972ee-e1af-3da5-6846-36b89a041fa4 SmartBots Franchise
```

### Example 2 — Filter by name (“earn2life”)

```
https://www.mysmartbots.com/api/bot.html?action=avatar_groups&botname=BarKeeeper%20Resident&avatar=cd93067e-7c4e-41c0-ba91-be01f4bafe35&matchnames=earn2life
```

**Response:**

```
0ec6f039-1a39-339c-3c68-e31ed2dc703f Earn2Life.com Discount Shops
24dcd8e6-3406-1518-b9ba-8653c1be09eb Earn2Life.com partnership
41ff4c6b-e3c0-a2b9-f53b-797e78532374 Earn2Life - earn L$500-1000 a day
4fbbee90-b278-e1b9-0ec9-251da2390c6c Earn2Life.com Investors (EARN)
5c63bbff-7064-0849-e8a7-25dff3d1765f Earn2Life.com Training Group
9e325390-c5e0-de09-3921-1501d34f9b38 Earn2Life Pay4Observe Support
```