> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/historical-occupancy/reporting-api-overview/presence-time.md). # Presence Time Presence time refers to the total duration (in seconds) that people were detected within an area during a specified time range. This metric is derived from presence sensor data and provides valuable insights into how long spaces are occupied and used. Below are guidelines for retrieving and analyzing presence time data for total duration within a selected time range. {% hint style="success" %} **Recommended Practices** 1. **Function Selection for Presence Time Metrics:** * Use the `sum` function to capture total utilization within the specified time window. 2. **Avoid Relative Time Queries:** Do not use relative time functionality (e.g., `-5m`) as it may result in missing data depending on query timing. Always specify absolute ***start*** and ***stop*** times. 3. **Include Zero Values in Output:** To ensure zero values are included in the results, add the filter: 
"filter": { "value": { "gte": 0 } }
{% endhint %} {% hint style="info" %} **NOTE:** Presence time data is available starting from **November 12, 2024**.\ This data is only available for spaces with presence mode sensors installed. {% endhint %} Below are sample queries for retrieving presence time data for floors, rooms, or zones. These queries allow you to analyze the total duration within a specified time range.

Presence time

### Floor Presence Time (Seconds) Use the sample query below to retrieve the total presence time (in seconds) for areas covered by presence sensors on the floor. Keep in mind that the sensor coverage area influences the measurement and may not represent the actual time spent across the entire floor. Query the **total hourly presence time (seconds)** of a floor with presence sensors installed: {% hint style="info" %} Use measurement: **`floor_presence_time_secs`** Use function: **`sum`** {% endhint %}
Request ```json // POST https://api.butlr.io/api/v3/reporting { "window": { "every": "1h", "function": "sum", "timezone": "Europe/Amsterdam" }, "filter": { "start": "2024-01-01T04:00:00Z", "stop": "2024-01-02T04:00:00Z", "measurements": ["floor_presence_time_secs"], "spaces": { "eq": ["space_2qfew8mjwwek7JwLY1zS9cgyPo6"] } }, "group_by": { "order": ["time"] } } ```
Response ```json // POST https://api.butlr.io/api/v3/reporting { "data": { "2024-01-01T04:00:00Z": { "sum": 213, "min": 213, "max": 213, "count": 1, "mean": 213, "median": 213, "stddev": 0, "first": 213, "last": 213 } } } ```
### Room Presence Time (Seconds) Use the sample queries below to retrieve the total presence time (in seconds) for areas covered by presence sensors in the room. Keep in mind that the sensor coverage area influences the measurement and may not represent the actual time spent across the entire room. Query the **total hourly presence time (seconds)** of a room with presence sensors installed: {% hint style="info" %} Use measurement: **`room_presence_time_secs`** Use function: **`sum`** {% endhint %}
Request ```json /// POST https://api.butlr.io/api/v3/reporting { "window": { "every": "1h", "function": "sum", "timezone": "Europe/Amsterdam" }, "filter": { "start": "2024-01-01T04:00:00Z", "stop": "2024-01-02T04:00:00Z", "measurements": ["room_presence_time_secs"], "rooms": { "eq": ["room_2qfew7oRPTDPQ0f7X9ZotfoiI3w"] } }, "group_by": { "order": ["time"] } } ```
Response ```json // POST https://api.butlr.io/api/v3/reporting { "data": { "2024-01-01T04:00:00Z": { "sum": 12, "min": 12, "max": 12, "count": 1, "mean": 12, "median": 12, "stddev": 0, "first": 12, "last": 12 } } } ```
### Zone Presence Time (Seconds) Use the sample queries below to retrieve the total presence time (in seconds) for areas covered by presence sensors in the zone. Keep in mind that the sensor coverage area influences the measurement and may not represent the actual time spent across the entire zone. Query the **total hourly presence time (seconds)** of a zone with presence sensors installed: {% hint style="info" %} Use measurement: **`zone_presence_time_secs`** Use function: **`sum`** {% endhint %}
Request ```json // POST https://api.butlr.io/api/v3/reporting { "window": { "every": "1h", "function": "sum", "timezone": "Europe/Amsterdam" }, "filter": { "start": "2024-01-01T04:00:00Z", "stop": "2024-01-02T04:00:00Z", "measurements": ["zone_presence_time_secs"], "zones": { "eq": ["zone_2qfew7oRPTDPQ0f7X9ZotfoiI3w"] } }, "group_by": { "order": ["time"] } } ```
Response ```json // Some code// POST https://api.butlr.io/api/v3/reporting { "data": { "2024-01-01T04:00:00Z": { "sum": 3, "min": 3, "max": 3, "count": 1, "mean": 3, "median": 3, "stddev": 0, "first": 3, "last": 3 } } } ```
[^1]: remove? --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.butlr.io/historical-occupancy/reporting-api-overview/presence-time.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.