# Label

Labels are pre-defined or custom key / value pairs that can be tied to elements for easy recognition and selection.

The following elements in the platform can have labels:

* [ApplicationBuild](/game-hosting/elements/application/applicationbuild.md)
* [ApplicationInstance](/game-hosting/elements/application/applicationinstance.md)
* [Host](/game-hosting/elements/host.md)

## Structure

| Property | Value type | Required | Description            |
| -------- | ---------- | -------- | ---------------------- |
| key      | string     | Yes      | The name of the label  |
| value    | string     | Yes      | The value of the label |

Table 1: Label element structure

## Requirements

A Label element has the following constraints:

* allowed characters in the label key are a-z 0-9 \_ -
* the label key may be no longer than 50 characters
* the label value may be no longer than 150 characters

## Adding & updating labels

Labels in the ApplicationBuild and ApplicationInstance elements are stored as an array of Label elements:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "labelPublic": [
    {
      "key": "label1",
      "value": "A value"
    },
    {
      "key": "label2",
      "value": "Another value"
    }
  ]
}
```

Figure 1: Example labels for an ApplicationInstance element

When you want to add a new label, you can PUT an element with only that new label. You would submit:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "labelPublic": [
    {
      "key": "label3",
      "value": "A new value"
    }
  ]
}
```

Figure 2: Example of adding a new label to an ApplicationInstance element

The result will be that the element has 3 labels: `label1`, `label2` and `label3`.

When you want to update a label, you only have to submit that one label for the element:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "labelPublic": [
    {
      "key": "label2",
      "value": "An updated value"
    }
  ]
}
```

Figure 3: Example of updating an existing label of an ApplicationInstance element

Deleting a label is done by submitting a label with a null value:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "labelPublic": [
    {
      "key": "label2",
      "value": null
    }
  ]
}
```

Figure 4: Example of deleting a label from an ApplicationInstance element

After these example mutations, the element ends up with the following labels:

`GET /applicationInstance/{applicationInstanceId}`

```
{
  "labelPublic": [
    {
      "key": "label1",
      "value": "A value"
    },
    {
      "key": "label3",
      "value": "A new value"
    }
  ]
}
```

Figure 5: The resulting labels for an ApplicationInstance element after applying the examples

## Pre-defined labels

For ApplicationInstance elements, the platform creates a number of default labels (platform defined labels):

* application\_id
* fleet\_id
* host\_id
* dc\_location\_id
* region\_id
* region\_name
* application\_build\_id

These labels are always present for all ApplicationInstance elements. It does mean that user-defined labels cannot have the same name as platform defined labels. These names are reserved.

## Using labels

Labels can be used to trim selections of elements.

In the API v3, using labels is done by adding a label expression as an URL query parameter.

An example of a label expression:

```
region_id=123 and fleet_id=456 or host_id=46256
```

When used in an API v3 request the expression must be url encoded:

```
GET /applicationInstance?labels=region_id%3D123%20and%20fleet_id%3D456%20or%20host_id%3D46256
```

If you filter on region\_name (or any other label with a string value) you must wrap the search value in double quotes:

```
region_name="Rotterdam"
```

The url encoded request:

```
GET /applicationInstance?labels=region_name%3D%22Rotterdam%22
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.i3d.net/game-hosting/elements/application/label.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.