# Query Occupancy by Tag

**Tag Occupancy** provides the total number of people across all tagged rooms or zones at a specific time. For instance, you can assign tags to these spaces if you want to track activity in meeting rooms, cafeterias, or lounge areas. This lets you filter or aggregate data by tag, helping uncover valuable insights about how these areas are used.

{% hint style="info" %}
Note: Only data from **presence-based** rooms and zones is available via Tag Occupancy.
{% endhint %}

<figure><img src="https://3289302098-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe3YixUK5tCcflJxye0bT%2Fuploads%2Fgit-blob-67185e70c5fcb69cf6453a32bb79b1f1e576a457%2Foccupancy%20by%20tag.png?alt=media" alt=""><figcaption></figcaption></figure>

### Tag Filtering

To filter occupancy by tag, include a list of tags in your query. This will allow you to retrieve only the floors, rooms, or zones associated with the specified tags.

<details>

<summary>Request</summary>

```json
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "max",
        "timezone": "Europe/Amsterdam" 
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["room_occupancy"],
        "tags": {
            "eq": ["tag_2qfewAEoTVaIWQaOY0WZlD729pr"] // This tag expands to a set of room_ids
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "occupancy",
            "measurement": "occupancy",
            "time": "2024-01-01T04:00:00Z",
            "value": 2
            "tag_id": "tag_2qfewAEoTVaIWQaOY0WZlD729pr",
            // ... more fields
        }
        // ... more data
    ]
}
            
```

</details>

### Tag Aggregation

To query data across multiple rooms and zones, aggregated by tag, you can use the `tag_occupancy`measurement. This can provide peak occupancy data across all associated rooms and zones. It is **highly recommended** to group this data by `tag_id`.

<details>

<summary>Request</summary>

```json
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "max",
        "timezone": "Europe/Amsterdam" 
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["tag_occupancy"],
        "tags": {
            "eq": ["tag_2qfewAEoTVaIWQaOY0WZlD729pr"]
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "occupancy",
            "measurement": "occupancy",
            "time": "2024-01-01T04:00:00Z",
            "value": 2
            "tag_id": "tag_2qfewAEoTVaIWQaOY0WZlD729pr",
            // ... more fields
        }
        // ... more data
    ]
}
```

</details>

{% hint style="danger" %}
**Tag History Not Supported:**\
Our system currently does not retain a history of tag changes.\
For example, if Zones 1–5 are tagged as "Marketing" in September and updated to "Finance" in December, the original tag ("Marketing") will no longer be available for queries. Only the current tag assignment ("Finance") can be queried. Historical comparisons or analyses based on previous tags must be managed outside the system.
{% endhint %}