Traffic

https://api.butlr.io/api/v3/reporting

Traffic measures the flow of people entering and leaving a space. It tracks entries (Ins) and exits (Outs), providing data that can be aggregated or filtered by floors, rooms, or zones. This metric relies on traffic sensors placed at key access points to monitor movement over time accurately.

Response fields

Traffic responses contain per-bucket counters and, since August 3, 2026, their cumulative counterparts:

Field	Meaning
in	Entries counted during the time bucket
out	Exits counted during the time bucket
in_csum	Cumulative entries since the daily reset (local midnight, per the query timezone)
out_csum	Cumulative exits since the daily reset
delta_sum	Net change during the bucket (in − out)
delta_csum	Cumulative net change since the daily reset

The cumulative fields are additive — in/out values and semantics are unchanged. Use in_csum at the end of a day for the day's total entries without summing buckets yourself.

Recommended Practices

1. Traffic Metrics: Use the sum function to aggregate the total entries and exits over the defined period.

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. Timezone Configuration: Always provide a timezone when querying traffic-based occupancy

4. Include Zero Values in Output: To ensure zero values are included in the results, add the filter:

   "filter": { "value": { "gte": 0 } }

Query the total hourly entrances and exits at a room or floor entrance.

Use measurement: traffic

Use function: sum

Request

// POST https://api.butlr.io/api/v3/reporting

{
    "window": {
        "every": "1h",
        "function": "sum",
        "timezone": "America/New_York" // replace with your timezone
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["traffic"],
        "rooms": {
            "eq": ["room_2qfewCOsBcP2ylz62KeUDgdr0Is"]
        }
    },
    "group_by": {
      "order": ["time", "field"]
    }
}

Response

{
  "data": {
    "2024-01-01T04:00:00": {
      "in": {
        "sum": 63, // total entrances over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      },
     "out": {
        "sum": 51, // total exits over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      }
    },
    "2024-01-01T05:00:00": {
      "in": {
        "sum": 12, // total entrances over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      },
     "out": {
        "sum": 17, // total exits over the hour
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
      }
    },
    // ... more data
  }
}