# 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="/files/C5HK5Gq59HZV1r4ATbFR" 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 %}


---

# 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.butlr.io/historical-occupancy/reporting-api-overview/query-occupancy-by-tag.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.