Query and List Devices

This section covers how to list devices in a location and query their current status.

Devices in SmartThings are organized by location and expose their functionality through capabilities.Your application only has access to the devices granted to it during the OAuth 2.0 process.

Generally, you do not need to include a location_id in requests to list devices, because your app is installed in a single location. It also means that if your app requested the r:devices:$ scope instead of r:devices:*, the list will contain only devices selected by the user during the authorization flow.

Device Model

A SmartThings device is structured as follows:

A device has one or more components (e.g. main, outlet1, outlet2)
Each component has one or more capabilities (e.g. switch, switchLevel, colorControl)
Each capability has attributes (e.g. the switch capability has a switch attribute with values on or off) and commands (e.g. on, off)

🔌 Device (The physical or virtual hardware)
│
└── 🧩 Component (A distinct, controllable part of the device)
  │  ↳ e.g., `main`, `outlet1`, `outlet2`
  │
  └── ⚙️ Capability (A specific function of that component)
    │  ↳ e.g., `switch`, `switchLevel`, `colorControl`
    │
    ├── 📋 Attributes (The current state or reading)
    │      ↳ e.g., `switch` is "on" or "off"
    │
    └── ✨ Commands (Actions to change the state)
         ↳ e.g., `on()`, `off()`, `setLevel(50)`

List Devices

Retrieve a list of devices in a location, optionally filtered by capability. The following example lists all devices with the switch capability. If you omit the capability query parameter, you will receive a list of all devices your app can access.

Request

GET https://api.smartthings.com/v1/devices?capability=switch HTTP/1.1
Accept: application/json
Authorization: Bearer {access_token}

Query Parameter	Description
`capability`	Filter devices by capability (e.g. `switch`, `switchLevel`, `temperatureMeasurement`)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
   {
     "deviceId": "80e26532-85d4-484c-b012-1c04f3d35f95",
     "name": "c2c-rgbw-color-bulb",
     "label": "Color & Tunable White Bulb",
     "manufacturerName": "SmartThings",
     "locationId": "95efee9b-6073-4871-b5ba-de6642187293",
     "components": [
       {
         "id": "main",
         "label": "main",
         "capabilities": [
           { "id": "switch", "version": 1 },
           { "id": "switchLevel", "version": 1 },
           { "id": "colorControl", "version": 1 },
           { "id": "colorTemperature", "version": 1 },
           { "id": "refresh", "version": 1 },
           { "id": "healthCheck", "version": 1 }
         ],
         "categories": [
           { "name": "Light", "categoryType": "manufacturer" }
         ]
       }
     ],
     "type": "VIPER"
   },
   {
     "deviceId": "af8a2a04-eba2-47f5-b388-e36663d92f81",
     "name": "Two Channel Outlet",
     "label": "Two Channel Outlet (dev)",
     "manufacturerName": "SmartThingsCommunity",
     "locationId": "95efee9b-6073-4871-b5ba-de6642187293",
     "components": [
       {
         "id": "main",
         "label": "main",
         "capabilities": [
           { "id": "switch", "version": 1 },
           { "id": "healthCheck", "version": 1 }
         ],
         "categories": [
           { "name": "SmartPlug", "categoryType": "manufacturer" }
         ]
       },
       {
         "id": "outlet1",
         "label": "outlet1",
         "capabilities": [
           { "id": "switch", "version": 1 }
         ],
         "categories": [
           { "name": "SmartPlug", "categoryType": "manufacturer" }
         ]
       },
       {
         "id": "outlet2",
         "label": "outlet2",
         "capabilities": [
           { "id": "switch", "version": 1 }
         ],
         "categories": [
           { "name": "SmartPlug", "categoryType": "manufacturer" }
         ]
       }
     ],
     "type": "VIPER"
   },
   {
     "deviceId": "b9af18af-55c8-4441-83e2-bfe6021235c4",
     "name": "c2c-dimmer",
     "label": "Dimmer",
     "manufacturerName": "SmartThings",
     "locationId": "95efee9b-6073-4871-b5ba-de6642187293",
     "components": [
       {
         "id": "main",
         "label": "main",
         "capabilities": [
           { "id": "switch", "version": 1 },
           { "id": "switchLevel", "version": 1 },
           { "id": "refresh", "version": 1 },
           { "id": "healthCheck", "version": 1 }
         ],
         "categories": [
           { "name": "Light", "categoryType": "manufacturer" }
         ]
       }
     ],
     "type": "VIPER"
   }
 ],
 "_links": {}
}

Key Fields

Field	Description
`items`	Array of device objects
`deviceId`	Unique identifier for the device
`name`	The device type name
`label`	User-assigned label for the device (what your app displays to users)
`manufacturerName`	Device manufacturer
`locationId`	The location this device belongs to
`components`	Array of device components, each with an `id` and list of `capabilities`
`components[].id`	Component identifier (e.g. `main`, `outlet1`)
`components[].capabilities`	Array of capabilities the component supports
`components[].categories`	Device category information (e.g. `Light`, `SmartPlug`)
`_links`	Pagination links (empty when all results fit in one page)

note

The device list response does not include the current state of device attributes. You must query the status separately for each device.

Get Device Capability Status

To get the current state of a specific capability on a device, query the capability status endpoint.

Request

GET https://api.smartthings.com/v1/devices/{deviceId}/components/{componentId}/capabilities/{capabilityId}/status HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer {access_token}

Path Parameter	Description
`deviceId`	The device identifier
`componentId`	The component to query (e.g. `main`)
`capabilityId`	The capability to query (e.g. `switch`)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "switch": {
   "value": "on",
   "timestamp": "2026-03-12T15:14:28.016Z"
 }
}

The response is a JSON object keyed by the attribute name. Each attribute has:

Field	Description
`value`	The current value of the attribute (e.g. `"on"`, `"off"` for the switch capability)
`timestamp`	ISO 8601 timestamp of when the value was last updated

Multiple Devices

To display the status of multiple devices, your app can query the capability status for each device individually. These requests can be made in parallel for better performance. For example, after listing three switch devices, your app would make three concurrent requests:

GET /devices/80e26532-.../components/main/capabilities/switch/status
GET /devices/af8a2a04-.../components/main/capabilities/switch/status
GET /devices/b9af18af-.../components/main/capabilities/switch/status

Get Complete Device Status

You can also get the status of all capabilities for a device with a single request to the device status endpoint:

Request

GET https://api.smartthings.com/v1/devices/{deviceId}/status HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer {access_token}

Response

This will return a JSON object containing the current value of all attributes for all capabilities on all components of the device. This is more efficient than querying each capability separately, but it may return more data than you need if you're only interested in a few attributes.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "components": {
        "main": {
            "colorControl": {
                "saturation": {
                    "value": 100,
                    "timestamp": "2026-04-28T18:48:24.934Z"
                },
                "color": {
                    "value": null
                },
                "hue": {
                    "value": 60,
                    "timestamp": "2026-04-28T18:48:24.918Z"
                }
            },
            "switchLevel": {
                "levelRange": {
                    "value": {
                        "maximum": 100,
                        "minimum": 1
                    },
                    "unit": "%",
                    "timestamp": "2026-04-28T18:30:30.453Z"
                },
                "level": {
                    "value": 50,
                    "unit": "%",
                    "timestamp": "2026-04-28T18:48:24.932Z"
                }
            },
            "synthetic.lightingEffectFade": {
                "fade": {
                    "value": null
                }
            },
            "switch": {
                "switch": {
                    "value": "on",
                    "timestamp": "2026-04-28T18:45:19.820Z"
                }
            },
            "colorTemperature": {
                "colorTemperatureRange": {
                    "value": {
                        "maximum": 6500,
                        "minimum": 1800
                    },
                    "unit": "K",
                    "timestamp": "2026-04-28T18:30:30.359Z"
                },
                "colorTemperature": {
                    "value": 2842,
                    "unit": "K",
                    "timestamp": "2026-04-28T18:30:30.344Z"
                }
            },
            "synthetic.lightingEffectCircadian": {
                "circadian": {
                    "value": {
                        "timeZoneId": "America/New_York",
                        "state": "Stop"
                    },
                    "timestamp": "2025-10-31T18:06:35.509Z"
                }
            }
        }
    }
}

Get Complete Information in a List of Devices

If your application requires the current state and health for most or all devices in a location, you can return capability status and device health directly within the device list response payload. This approach eliminates the need to execute separate status requests for individual devices. To include this comprehensive data in your response, set the includeStatus and includeHealth query parameters to true.

If you only need the complete status for a specific type of device, be sure to combine these parameters with a capability filter to avoid fetching heavy payloads for devices you do not care about.

Performance Best Practice: Optimizing Device Queries

Only set includeStatus and includeHealth parameters to true if your application requires this information for most, or all, of the devices in the resulting list (for example, when rendering a dashboard of current device states).

These parameters increase the response payload size and processing time - avoid using them if you only need the status for a small subset of devices, or when a user views the details of a specific device. In these cases, it is more efficient to omit these parameters and make individual capability status queries as needed.

Request

GET https://api.smartthings.com/v1/devices?includeStatus=true&includeHealth=true HTTP/1.1
Authorization: Bearer {access_token}

Response

The response will include the same device information as before, but each device object will now have an additional status field containing the current value of all attributes for all capabilities on all components of the device, as well as a health field with the current health status.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "deviceId": "c3ebc842-7a47-47f1-bb97-4ebb8ef534c0",
      "ownerId": "c257d2c7-332b-d60d-808d-550bfbd54556",
      "name": "Food Waste Disposer",
      "label": "Food Waste Disposal",
      "deviceManufacturerCode": "STS",
      "manufacturerName": "SmartThingsCommunity",
      "deviceModel": "custom-food-waste-disposal",
      "presentationId": "3cc33789-ec49-3b77-8629-3bfad351b116",
      "locationId": "d768125b-abb6-46ea-9e73-2eb58b82d0db",
      "components": [
        {
          "id": "main",
          "label": "main",
          "capabilities": [
            {
              "id": "foodWasteDryingGrinder",
              "version": 1,
              "optional": false,
              "status": {
                "mode": {
                  "value": "auto",
                  "timestamp": "2026-04-08T15:22:05.134Z"
                },
                "supportedStates": {
                  "value": [
                    "waiting",
                    "running",
                    "drying",
                    "grinding",
                    "cooling",
                    "cleaning",
                    "error"
                  ],
                  "timestamp": "2026-04-08T15:22:05.134Z"
                },
                "state": {
                  "value": "waiting",
                  "timestamp": "2026-04-08T15:22:05.134Z"
                },
                "supportedModes": {
                  "value": [
                    "auto",
                    "standard",
                    "power",
                    "eco",
                    "storage",
                    "clean"
                  ],
                  "timestamp": "2026-04-08T15:22:05.134Z"
                },
                "event": {
                  "value": null
                },
                "supportedEvents": {
                  "value": [
                    "operationComplete",
                    "cleaningComplete"
                  ],
                  "timestamp": "2026-04-08T15:22:05.134Z"
                }
              }
            },
            {
              "id": "healthCheck",
              "version": 1,
              "optional": false,
              "status": {
                "checkInterval": {
                  "value": 60,
                  "unit": "s",
                  "data": {
                    "deviceScheme": "UNTRACKED",
                    "protocol": "cloud"
                  },
                  "timestamp": "2026-04-08T15:22:02.825Z"
                },
                "healthStatus": {
                  "value": null
                },
                "DeviceWatch-Enroll": {
                  "value": null
                },
                "DeviceWatch-DeviceStatus": {
                  "value": "offline",
                  "data": {
                    "reason": "INVALID-ACCESS-TOKEN"
                  },
                  "timestamp": "2026-04-10T09:25:11.029Z"
                }
              }
            }
          ],
          "categories": [
            {
              "name": "Others",
              "categoryType": "manufacturer"
            }
          ],
          "optional": false
        }
      ],
      "createTime": "2026-04-08T15:22:02.623Z",
      "healthState": {
        "state": "OFFLINE",
        "lastUpdatedDate": "2026-04-10T09:25:11.064Z"
      },
      "profile": {
        "id": "749b7b67-ccb2-3783-9743-59c4cbd10678"
      },
      "viper": {
        "uniqueIdentifier": "bc74a09e-a92e-41f8-9587-b38aa89e7572",
        "manufacturerName": "STS",
        "modelName": "custom-food-waste-disposal",
        "endpointAppId": "viper_3abd9ca0-b0ef-11ec-b276-0f194eeb05e4"
      },
      "type": "VIPER",
      "vid": "3cc33789-ec49-3b77-8629-3bfad351b116",
      "mnmn": "SmartThingsCommunity",
      "ocfDeviceType": "oic.wk.d",
      "restrictionTier": 0,
      "allowed": [],
      "executionContext": "CLOUD",
      "relationships": []
    }
  ],
  "_links": {}
}

Up Next

Now that you can list devices and read their status, visit Control Devices to learn how to send commands to devices.

Device Model​

List Devices​

Request​

Response​

Key Fields​

Get Device Capability Status​

Request​

Response​

Multiple Devices​

Get Complete Device Status​

Request​

Response​

Get Complete Information in a List of Devices​

Request​

Response​

Up Next​

Device Model

List Devices

Request

Response

Key Fields

Get Device Capability Status

Request

Response

Multiple Devices

Get Complete Device Status

Request

Response

Get Complete Information in a List of Devices

Request

Response

Up Next