> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/scripting/api-reference/alias-api.md).

# Alias API

{% hint style="warning" %}
Script Aliases are currently an **Experimental Feature**.
{% endhint %}

### `sp.alias.<name>`

Returns the first Object or Parameter assigned to the specified Alias.

```python
sp.alias.tracker
```

If the Alias targets an Object, the returned Object handle can be used normally:

```python
sp.alias.tracker.coordinates.position.value
```

If the Alias targets a Parameter, the Parameter handle is returned directly:

```python
sp.alias.posi.value
```

Values can also be written through a Parameter Alias:

```python
sp.alias.posi.value = [99, 88, 77]
```

If multiple targets use the same Alias name, the first matching target is returned.

### `sp.alias.first.<name>`

Explicitly returns the first target matching the specified Alias name.

```python
sp.alias.first.tracker
```

This is equivalent to directly accessing:

```python
sp.alias.tracker
```

when multiple targets use the same Alias name.

### `sp.alias.all.<name>`

Returns all targets using the specified Alias name.

```python
sp.alias.all.tracker
```

The returned targets can be iterated:

```python
for tracker in sp.alias.all.tracker:
    print(tracker)
```

Object and Parameter handles returned this way can be used normally:

```python
for tracker in sp.alias.all.tracker:
    print(tracker.coordinates.position.value)
```

Parameter Aliases can be handled in the same way:

```python
for pos in sp.alias.all.pos:
    print(pos.value)
```

### `sp.alias.random.<name>`

Returns one random target using the specified Alias name.

```python
sp.alias.random.tracker
```

This is useful when multiple targets share the same Alias and only one random matching target is required.

### Bracket Notation

Bracket notation can be used when an Alias name contains spaces or special characters that cannot be accessed using regular dot notation.

```python
sp.alias["tracker with special chars & $"]
```

### Wildcard Matching

Bracket notation also supports wildcard matching using `*`.

```python
sp.alias["tracker*"]
```

This returns an array containing all matching Alias targets.

For example:

```python
for tracker in sp.alias["tracker*"]:
    print(tracker)
```

A pattern such as:

```
tracker*
```

can match Alias names such as:

```
trackerLeft
trackerRight
trackerCenter
```

{% hint style="info" %}
Alias wildcard matching currently supports `*`.
{% endhint %}

### Missing Aliases

If a directly requested Alias does not exist, the result is `None`.

```python
sp.alias.doesNotExist
```

Trying to access additional properties on the missing result causes a script error:

```python
sp.alias.doesNotExist.value
```

The error is reported in the Grid Studio Log.

### Quick Reference

| API                      | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `sp.alias.<name>`        | Returns the first matching Alias target         |
| `sp.alias.first.<name>`  | Explicitly returns the first matching target    |
| `sp.alias.all.<name>`    | Returns all targets with the specified Alias    |
| `sp.alias.random.<name>` | Returns one random matching target              |
| `sp.alias["name"]`       | Accesses an Alias using bracket notation        |
| `sp.alias["pattern*"]`   | Returns all targets matching a wildcard pattern |