> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iotee.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Lock Events

> Query lock and unlock events across devices.

Returns a paginated list of lock and unlock events. Results are automatically scoped to devices within your access.

## Query parameters

<ParamField query="hardware_id" type="string">
  Filter by device hardware ID.
</ParamField>

<ParamField query="source" type="string">
  Filter by event source: `rfid`, `keypad`, `key`, or `remote`.
</ParamField>

<ParamField query="event" type="string">
  Filter by event type: `lock` or `unlock`.
</ParamField>

<ParamField query="code" type="string">
  Find events by RFID tag or keypad code.
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 date string (start of time range).
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 date string (end of time range).
</ParamField>

<ParamField query="limit" type="number" default="100">
  Max results per page (1–1000).
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset.
</ParamField>

## Response

<ResponseField name="events" type="object[]" required>
  Array of lock event objects.

  <Expandable title="Lock event object">
    <ResponseField name="event_id" type="string" required>Unique event identifier.</ResponseField>
    <ResponseField name="hardware_id" type="string" required>Device hardware ID.</ResponseField>
    <ResponseField name="event" type="string" required>`lock` or `unlock`.</ResponseField>
    <ResponseField name="timestamp" type="string" required>ISO 8601 timestamp.</ResponseField>
    <ResponseField name="source" type="string" required>`rfid`, `keypad`, `key`, or `remote`.</ResponseField>
    <ResponseField name="code" type="string">RFID tag or keypad code (for `rfid`/`keypad` sources).</ResponseField>
    <ResponseField name="metadata" type="object">Custom data from the API command (for `remote` source).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  <Expandable title="Pagination object">
    <ResponseField name="limit" type="number" required>Requested page size.</ResponseField>
    <ResponseField name="offset" type="number" required>Requested offset.</ResponseField>
    <ResponseField name="returned" type="number" required>Results in this page.</ResponseField>
  </Expandable>
</ResponseField>

## Event sources

| Source   | `code` field   | `metadata` field | Triggered by    |
| -------- | -------------- | ---------------- | --------------- |
| `rfid`   | RFID tag value | —                | Device hardware |
| `keypad` | Code entered   | —                | Device hardware |
| `key`    | —              | —                | Physical key    |
| `remote` | —              | Optional         | API command     |

<RequestExample>
  ```bash All events theme={null}
  curl -H "X-API-Key: YOUR_API_KEY" \
    https://your-api-host/lock-events
  ```

  ```bash Filter by device and source theme={null}
  curl -H "X-API-Key: YOUR_API_KEY" \
    "https://your-api-host/lock-events?hardware_id=ABC123&source=rfid"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "events": [
      {
        "event_id": "evt_123",
        "hardware_id": "ABC123",
        "event": "unlock",
        "timestamp": "2025-12-17T10:30:00.000Z",
        "source": "rfid",
        "code": "ABC123"
      },
      {
        "event_id": "evt_124",
        "hardware_id": "ABC123",
        "event": "unlock",
        "timestamp": "2025-12-17T14:00:00.000Z",
        "source": "remote",
        "metadata": {
          "userId": "user_456",
          "name": "Jane Smith"
        }
      }
    ],
    "pagination": {
      "limit": 100,
      "offset": 0,
      "returned": 2
    }
  }
  ```
</ResponseExample>