# nearbyavatars_scan

Scans the current region for other avatars.


:::warning
This API call might not be suitable for LSL because of the large amount of data received.

:::

```csharp
// See "LSL Helper Functions" page for this function
smartbotsAPI("nearbyavatars_scan", []);
```

# Variables

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

## Input basic parameters

| Variable | Required | Description |
|----------|----------|-------------|
| action   | yes      | = nearbyavatars_scan |
| 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 caller script. This value will be returned back to the caller in HTTP response |

## Input

This command has no additional input parameters.

## 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. See above |
| avatars  | Nearby avatars list. See **Return value** for details |

# Return value

The `avatars` field in the response is an array containing a list of avatars the bot can see:

```json
{
  "name": "GrrrillaBongo Resident",
  "UUID": "d8e20552-ca84-4c42-b8d3-e8fa5fbdcc6b",
  "parcelID": 177,
  "sitting": false,
  "position": {
    "X": 110,
    "Y": 75,
    "Z": 32
  },
  "localPosition": {
    "X": 110,
    "Y": 75,
    "Z": 32
  },
  "heading": 0,
  "localHeading": 0,
  "distance": 129.97195,
  "seenSince": "2022-10-18T12:36:58.2626463Z",
  "seenSeconds": 123
}
```

# Details

The `seenSince` value indicates when the bot first detected a specific avatar during `nearbyavatars_scan`.  
For example:


1. The bot logs in.
2. Time passes (say, 1 hour).
3. `nearbyavatars_scan` is called.
4. Bot sees avatar **Guest1**, `seenSince = "2022-10-18 13:00"`.
5. Five minutes later, `nearbyavatars_scan` is called again.
6. Bot now sees **Guest2**, `seenSince = "2022-10-18 13:05"`.

Subsequent calls to `nearbyavatars_scan` return:

```
Guest1: seenSince = "2022-10-18 13:00"
Guest2: seenSince = "2022-10-18 13:05"
```

The `seenSeconds` value shows how many seconds the avatar has been visible (difference between now and `seenSince`).

# Throttling

The maximum call rate for `nearbyavatars_scan` is **2 calls per 10 seconds**.  
Excessive calls will return a **"Frequent API requests throttled"** error.

# Data size

The data returned by this command can be large (up to **10 KB or more**), depending on the number of avatars nearby.