---
title: "Get Device State"
method: GET
path: "/get_device_state"
tags: ["Device Interactions"]
---

# Get Device State

`GET /get_device_state`

## Request

- Base URL: `https://api.developer.atomberg-iot.com/v2`
- URL: `https://api.developer.atomberg-iot.com/v2/get_device_state`
- Auth: API key in header `x-api-key` and HTTP bearer

Get the last known state of the device.

Some developers, especially those who keep querying the state of their fan(s) frequently, may soon hit the API limit with this API. For these developers, it is better to listen to the state of the fan(s) locally over UDP. If you would rather access the device state using an API rather than locally over UDP, skip the next section.

## Reading the state from the fan over UDP

**UDP state broadcasts are currently available for fans only.** To retrieve the state of water purifiers and smart locks, use the 'Get Device State' API.

Once the fan receives any command and takes action, it updates its state over UDP on the broadcast port (5625). The message is received in the hex format, and needs to be converted to ASCII. For example, the message received may be 


```plaintext
7b226465766963655f6964223a22613037363465356165653938222c226d6573736167655f6964223a2241636d42696a6d6f6d666e424a62486341222c2273746174655f737472696e67223a2232302c312c422c352c35302e30302c302c302c52312c323830322c312c34353134322c302c302c302c302c302e30302c302e30302c302c302c302c454e44227d
```


When converted to ASCII, the state message reads

```json
{
  "device_id":"a0764e5aee98",
  "message_id":"AcmBijmomfnBJbHcA",
  "state_string":"20,1,B,5,50.00,0,0,R1,2802,1,45142,0,0,0,0,0.00,0.00,0,0,0,END"
}

```


The message_id is a unique identifier for each message. This can help the system discard duplicates.

The state_string contains the current state of the fan, apart from a lot of other debug fields. The current state (speed, power, light brightness, etc.) can be decoded from the first field of the state string itself (the first field is 20 in the above example). Its decoding logic is given below:

```plaintext
var power = (0x10) & value > 0 ? true : false;
var led = (0x20) & value > 0 ? true : false;
var sleep = (0x80) & value > 0 ? true : false;
var speed = (0x07) & value;
var fanTimer = ((0x0F0000 & value) / 65536).round();
var fanTimerElapsedMins = ((0xFF000000 & value) * 4 / 16777216).round();

//Aris Starlight Specific
var Brightness = (((0x7F00) & value) / 256).round();
var Cool = ((0x08) & value) > 0 ? true : false;
var Warm = ((0x8000) & value) > 0 ? true : false;

If both Cool and Warm are true, then color is 'Daylight'
```

# Response fields by device type


The fields depend on the type of device. Fans report power and speed.
Purifiers report water quality and mode. Locks report battery and
firmware. There is a response example for each type below.


Fields marked firmware-dependent are only sent when the device's firmware
reports them. On older units these keys are missing from the response
(they are not null), so your code should handle missing keys.


## Fan fields


| Field | Type | Meaning |
| --- | --- | --- |
| power | boolean | Whether the fan is running |
| last_recorded_speed | integer | Last reported speed, 1-6. Kept while off |
| sleep_mode | boolean | Whether sleep mode is active |
| led | boolean | Whether the fan light is on |
| is_online | boolean | Whether the device is connected right now |
| timer_hours | integer | Duration the running timer was set for, 0 when none |
| timer_time_elapsed_mins | integer | Minutes elapsed on the running timer |
| ts_epoch_seconds | integer | When the device last reported |
| last_recorded_brightness | integer | Percentage. **M1, M2, S1, S2, M3, S3, I1, I5, O1** |
| last_recorded_color | string | warm / cool / daylight. **I1, I5, O1** |
| rev_mode | boolean | Whether the fan is running in reverse. **O1** |
| buzzer_status | boolean | Whether audible feedback is on. **O1** |


## Water purifier fields


| Field | Type | Meaning |
| --- | --- | --- |
| mode | integer | Active purification mode. 0, 1, 2, 3, 4 or 10 |
| fallback_mode | integer | Mode the unit falls back to. 0, 2, 3 or 4 (RO_ONLY or a TasteTune mode) |
| idle_sleep | 0 / 1 | Whether the display turns off while idle |
| tds_threshold | integer | RO vs UF threshold in ppm. *Firmware-dependent* |
| sleep_mode | 0 / 1 | Whether the daily sleep window is on. *Firmware-dependent* |
| start_utc | integer | Sleep window start, epoch. *Firmware-dependent* |
| stop_utc | integer | Sleep window end, epoch. *Firmware-dependent* |
| input_tds | number | Raw inlet water TDS, ppm |
| tank_tds | number | Raw stored water TDS, ppm |
| choking_faults | object | Flow blockage and valve faults, already decoded. **Not a single fault code.** Check `healthy` or look in `codes`. `null` if never reported |
| system_faults | object | Electrical, sensor and leak faults, already decoded. A separate bitmask with its own code table. `null` if never reported |


## Smart lock fields


Locks report battery, firmware and their settings. Credentials are
**never** returned. This means no PINs, fingerprint data or card IDs, and
no credential names or counts.


| Field | G1 Cypheo Elite | Azhero Smart Door Lock / SL1 |
| --- | --- | --- |
| battery | Yes | Yes |
| last_battery_time | Yes | Yes |
| n_unlocks | Yes | - |
| esp_fw_version | Yes | - |
| settings | door lock, motor, volume, child lock | - |

## Request

| Where | Name | Required | Value |
| --- | --- | --- | --- |
| Header | `x-api-key` | Yes | Your developer API key. |
| Header | `Authorization` | Yes | `Bearer <access_token>` |
| Query | `device_id` | Yes | One `device_id`, or `all` for every supported device. |

No request body.

Passing `all` returns every supported device on the account in **one** call,
which counts as one request against your quota. Reading six devices one by
one costs six. Devices that this API does not support are left out.

## Response

```json
{
  "status": "Success",
  "message": {
    "device_state": [
      {
        "device_id": "6867258b9d78",
        "power": true,
        "last_recorded_speed": 4,
        "sleep_mode": false,
        "led": true,
        "is_online": true,
        "timer_hours": 1,
        "timer_time_elapsed_mins": 12,
        "ts_epoch_seconds": 1756200000
      }
    ]
  }
}
```

`device_state` is always an array, even for one `device_id`. The fields in
each item depend on the device type. The tables above list them.

### What the values mean

This endpoint returns the **last state the device reported**. It does not
read the device live.

`is_online` tells you if the device is connected now. When it is `false`,
the other fields show the last known values. That is fine for a dashboard,
but do not treat them as current.

If the firmware has never reported a field, the field is **missing** (it is
not `null`). Older firmware on the same series can return fewer fields than
newer firmware. Use `.get(key)` in Python or `?.` in JavaScript to handle
this.

## Query parameters

- `device_id` string, required

## Response `200`

OK

- DeviceStateResponse
  - `status` string: `Success` on a 2xx, `Error` otherwise.
  - `message` object: The response data. Each endpoint has its own format.
    - `device_state` union[]: One entry for each device. Always an array, even for a single device_id. The fields depend on the device type (see the schemas below).
      - union
        - FanState
          - `device_id` string: The device this state belongs to.
          - `series` string: Hardware series. It tells you which optional fields to expect.
          - `power` boolean: Whether the fan is currently running.
          - `last_recorded_speed` integer: The speed the fan last reported. Kept while the fan is off.
          - `sleep_mode` boolean: Whether sleep mode is active.
          - `led` boolean: Whether the fan's light is on.
          - `is_online` boolean: Whether the device is connected to the platform right now.
          - `timer_hours` integer: Duration the running timer was set for. `0` when no timer is active.
          - `timer_time_elapsed_mins` integer: Minutes elapsed on the running timer.
          - `ts_epoch_seconds` integer: When the device last reported its state, in epoch seconds.
          - `last_recorded_brightness` integer: Light brightness as a percentage. Only returned by **M1, M2, S1, S2, M3, S3, I1, I5, O1**. Missing on other fan series.
          - `last_recorded_color` 'warm' | 'cool' | 'daylight': Colour temperature of the light. Present only on I1, I5, O1.
          - `rev_mode` boolean: Whether the fan is running in reverse. Only on **O1**.
          - `buzzer_status` boolean: Whether audible feedback is on. Present only on **O1**.
        - WaterPurifierState: Every purifier command has a matching field here, so you can check that a setting was applied.
          - `device_id` string: The device this state belongs to.
          - `is_online` boolean: Whether the purifier is connected right now. When false, the other fields show the last known values.
          - `ts_epoch_seconds` integer: When the device last reported its state, in epoch seconds.
          - `mode` 0 | 1 | 2 | 3 | 4 | 10: Active purification mode. `0` RO_ONLY, `1` ADAPTIVE, `2` TasteTune 50-100, `3` TasteTune 75-125, `4` TasteTune 100-150, `10` Vacay. TasteTune modes keep the TDS of purified water in that range (ppm).
          - `fallback_mode` 0 | 2 | 3 | 4: Mode the unit falls back to. Can be `0` (RO_ONLY) or a TasteTune mode (`2`, `3` or `4`). ADAPTIVE and Vacay are not allowed.
          - `idle_sleep` 0 | 1: Whether the display turns off while the unit is idle.
          - `tds_threshold` integer: Input TDS threshold in ppm that decides RO vs UF treatment. **Firmware-dependent**, missing on older units.
          - `sleep_mode` 0 | 1: Whether the daily sleep window is enabled. **Firmware-dependent**, missing on older units.
          - `start_utc` integer: Start of the daily sleep window, in epoch seconds. Only the time of day is used. **Firmware-dependent**.
          - `stop_utc` integer: End of the daily sleep window. **Firmware-dependent**.
          - `input_tds` number: Raw inlet water TDS reading, in ppm.
          - `tank_tds` number: Raw stored-water TDS reading, in ppm.
          - `choking_faults` object, nullable: Flow blockage and valve faults, already decoded. The device reports a uint16 bitmask, not one error code. Each bit is separate and several can be set at once, so this gives a list of codes. `null` when the device has never reported it.
            - `raw` integer: The bitmask as the device reported it.
            - `healthy` boolean: `true` when `raw` is `0`. Check this instead of `raw`.
            - `codes` string[]: One entry per set bit: RO_CHOKE, UF_CHOKE, PRE_RO_CHOKE, POST_RO_CHOKE, SV1_CHOKE, SV2_CHOKE, SV4_CHOKE, SV5_CHOKE. Empty when healthy.
            - `descriptions` string[]: A readable description of each code, in the same order as `codes`.
            - `filter_choke` boolean: A filter is choked (PRE_RO, RO, UF or POST_RO). Replacing the filter fixes it.
            - `sv_fault` boolean: A solenoid valve is faulty. These bits are set at about 5% of the expected flow, so they mean there is no flow, not a partial blockage.
            - `unknown_bits` integer: Bits not in the documented list, from older firmware or factory testing. Log the raw value, but do not show it to customers as a fault.
          - `system_faults` object, nullable: Electrical, sensor and leak faults, already decoded. This is a separate uint32 bitmask with its own code table. Do not decode it with the `choking_faults` table. A blocked valve is SV1_CHOKE in `choking_faults`. A failed valve driver is SV1_MOSFET_CHOKE here. `null` when the device has never reported it.
            - `raw` integer: The bitmask as the device reported it.
            - `healthy` boolean: `true` when `raw` is `0`. Check this instead of `raw`.
            - `codes` string[]: One entry per set bit: FLOW_SENSOR_FAILURE, INPUT_TDS_FAILURE, RO_TDS_FAILURE, TANK_TDS_FAILURE, TANK_INDICATION_FAILURE, TANK_FULL, NO_WATER, SV3_CHOKE, UV_CHOKE, PUMP_CHOKE, TEMP_SENSOR_LOOSE, SV1_MOSFET_CHOKE, SV2_MOSFET_CHOKE, SV3_MOSFET_CHOKE, SV4_MOSFET_CHOKE, SV5_MOSFET_CHOKE, PUMP_MOSFET_CHOKE, UV_MOSFET_CHOKE, SV1_SV2_LEAK, SV4_SV5_LEAK, RO_MEMBRANE_BURST, TANK_TDS_SV_LEAK. Empty when healthy.
            - `descriptions` string[]: A readable description of each code, in the same order as `codes`.
            - `unknown_bits` integer: Bits not in the documented list. Log them, but do not map them to a fault.
        - CypheoEliteLockState
          - `device_id` string: The lock this state belongs to.
          - `series` string: Always `G1` for a Cypheo Elite lock.
          - `is_online` boolean: Whether the lock is connected right now. Missing if the lock has never reported it.
          - `ts_epoch_seconds` integer: When this state was last reported, epoch seconds.
          - `battery` integer: Remaining battery as a percentage.
          - `last_battery_time` integer: When the battery level was last reported, epoch seconds.
          - `esp_fw_version` string: Firmware version of the Wi-Fi module.
          - `n_unlocks` integer: Total number of unlocks reported by the lock.
          - `settings` object: Lock behaviour as configured in the Atomberg Home app.
            - `door_auto_lock` boolean: Whether the door locks again by itself.
            - `door_auto_lock_timer` integer: Delay in seconds before auto-locking.
            - `door_open_alert_timer` integer: Seconds the door may stay open before the lock alerts.
            - `passage_mode` boolean: Whether the lock is held open for free passage.
            - `passage_mode_time` integer: How long passage mode stays on.
            - `volume` integer: Speaker volume level.
            - `motor_direction` integer: Which way the bolt moves. Set during installation.
            - `child_lock` boolean: Whether child lock is on for the keypad.

## Other responses

- `400`: The request is not valid, or the command is not supported by that device. The message names the wrong key and lists what the device accepts.
- `401`: The API key or token is missing, malformed or expired, or it is the wrong kind of token.
- `403`: Developer Mode is not enabled for this account, or the user does not exist. You also get a 403 when the URL path or HTTP method is wrong.
- `404`: The device is not on your account, or it has not reported any state yet.
- `429`: You have used up your API key's daily quota, or gone over the per-second limit. The daily quota resets at 00:00 UTC.
- `500`: Something failed on our side. Your request was fine. Try again after a short wait.
- `501`: This API does not support the device's series. The message lists the supported series.

## Changes

- **2026-10-07** `35290532bede`: 1 warning
  - removed the optional property `message/device_state/items/oneOf[subschema #1: Fan state]/custom_timer` from the response with the `200` status
- **2026-10-06** `30e1ea1bdb73`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/changes/get_device_state/get.md)

---

[API](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis.md) - [All operations](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/revisions/35290532bede?raw)
