> 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/integrations-api-third-party-sensors/reporting-api/touch-events.md).

# Touch Events

One data point per touch on a touch sensor.

| Measurement    | Data keyed by |
| -------------- | ------------- |
| `touch_events` | `room_id`     |

**Intervals:** none. This is an event measurement, so you can leave out `interval`, and any value sent is ignored. **Max range:** 730 days; see [Query Limits](/integrations-api-third-party-sensors/reporting-api/query-limits.md).

## Fields

| Field          | Description                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `event_type`   | `tactile_tap`. Older events, from before late June 2026, may carry `cleaning_done`.                |
| `sensor_3p_id` | Butlr ID of the sensor that was touched (`sensor3p_…`). Output only; it cannot be used as an item. |

Each point has `stop` equal to `start`, and carries room-level [location metadata](/integrations-api-third-party-sensors/reporting-api/items-and-fields.md#location-metadata).

## Notes

* **Room placement:** only sensors placed inside a room produce events.
* **`fill_gaps`:** not supported; the request fails with code `-5015`.

## Example: touches in a room over a week

```bash
curl -X POST https://api-integrations.butlr.io/api/v1/reporting \
  -H "Authorization: Bearer [insert access_token here]" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": ["touch_events"],
    "items": ["room_XXXX"],
    "start": "2026-09-14",
    "stop": "2026-09-21",
    "fields": ["event_type", "sensor_3p_id"]
  }'
```

```json
{
  "data": {
    "room_XXXX": [
      {
        "start": "2026-09-14T15:21:07Z",
        "stop": "2026-09-14T15:21:07Z",
        "event_type": "tactile_tap",
        "sensor_3p_id": "sensor3p_XXXX"
      },
      …
    ]
  }
}
```