Skip to main content

Fetching Events

Webhooks are the right tool for reacting to events in real time. Fetching events over the API is for the cases webhooks don't cover: backfilling history when you first connect a home, reconciling after your endpoint was unreachable, or building a view of what already happened.

Every request needs a valid access token — see Authentication for Users.

Get events for a home​

The recommended endpoint is GET /homes/{home_id}/events. You'll need the home_id — see Find your home IDs for how to list the homes your token can access.

curl --request GET 'https://api.minut.com/v8/homes/HOME_ID/events?limit=50&offset=0' \
     --header 'Authorization: Bearer ACCESS_TOKEN'

The response is a page of events under home_events, plus paging information:

{
  "home_events": [
    {
      "event_id": "5ffffeecb167b70039f8076f",
      "event_type": "noise_detected",
      "event_time": "2026-05-29T10:05:00.708Z",
      "home_id": "5ffff22ab167b70039f806fe"
    }
  ],
  "paging": {
    "total_count": 1,
    "limit": 50,
    "offset": 0
  }
}

The fields on each event vary by event_type; see the Events Reference for example payloads. Note that home events use their own type names (for example noise_detected, noise_quieted) rather than the user-event names.

Filtering​

GET /homes/{home_id}/events accepts a few query parameters:

  • event_type — a comma-separated list of home event types to include, e.g. event_type=noise_detected,noise_quieted. Omit it to get all types. Values are validated against the home event types, so use the home event names (not the user-event/webhook names).
  • start_at / end_at — restrict the window. Both are ISO-8601 timestamps in UTC, e.g. 2026-05-01T00:00:00Z.
  • limit / offset — page size and starting position (see below).
  • guest_ids — limit to events associated with specific guests.
curl --request GET 'https://api.minut.com/v8/homes/HOME_ID/events?event_type=noise_detected,noise_quieted&start_at=2026-05-01T00:00:00Z&end_at=2026-05-08T00:00:00Z' \
     --header 'Authorization: Bearer ACCESS_TOKEN'

Paginating​

Use limit and offset to walk through the full history. Increase offset by limit until you receive fewer events than you asked for:

import axios from 'axios'

async function fetchAllEvents(homeId, accessToken) {
  const limit = 100
  let offset = 0
  const all = []

  while (true) {
    const { data } = await axios.get(
      `https://api.minut.com/v8/homes/${homeId}/events`,
      {
        params: { limit, offset },
        headers: { Authorization: `Bearer ${accessToken}` },
      },
    )
    all.push(...data.home_events)
    if (data.home_events.length < limit) break
    offset += limit
  }

  return all
}

When reconciling against webhook deliveries, deduplicate on event_id.

Fetch a single event​

If you already have an event id, fetch it directly with GET /homes/{home_id}/events/{home_event_id}.

A note on /events​

There is an older GET /events endpoint that returns events for the authenticated user across their homes. It is deprecated in favour of the per-home endpoint above — prefer GET /homes/{home_id}/events for new integrations.

Don't poll for real-time data​

Fetching events on a tight loop won't get you faster updates — devices only report to the backend periodically (see Architecture), and aggressive polling can get your client rate limited (see API Information → Rate Limits). Use Webhooks for timely delivery and the endpoints here for history and reconciliation.