Controlling which lights will be operated on for a request.

Selectors are an identifier for addressing one or many lights belonging to the authenticated account. The most broad selector is all and the most narrow is id:d3b2f2d97452. Selectors with many lights will return an array of light objects, selectors with one light will return a light object.

Selectors can be static or dynamic. Static selectors are formatted as value and are the same for all lights. all is an example of a static selector. Dynamic selectors are formatted as type:value and the values are based on the current state of the lights. id:d3b2f2d97452 is an example of a dynamic selector.

Selectors which generally specify multiple lights, all, group, group_id, location, location_id, and scene_id, accept an optional suffix :random which specifies a single random light from that set of lights. e.g. all:random, group:[value]:random, location_id:[value]:random.

You can determine which values to use by inspecting the response from the lights endpoint.

Generally, you should avoid using label-based selectors (label, group, location) when developing an application as they will break if users rename the label, group or location. They are provided as convenient helpers for personal-level projects.

All selectors return a list for consistency, even id.

You can combine up to 25 selectors together additively by separating them with ,, so if you want to address both a light labelled "Bedroom" and a light labelled "Office", you can use label:Bedroom,label:Office as the selector.




All lights belonging to the authenticated account


Lights that match the label.


The light with the given id/serial number. Returns a list of one light.


The lights belonging to the group with the given ID


The lights belonging to the groups matching the given label


The lights belonging to the location matching the given ID


The lights belonging to the locations matching the given label


The lights that are referenced in the scene with the given ID

Dynamic Selectors

Given the following light:

  "id": "d3b2f2d97452",
  "label": "Left Lamp",
  "group": {
    "id": "1c8de82b81f445e7cfaafae49b259c71",
    "name": "Lounge",
  "location": {
    "id": "1d6fe8ef0fde4c6d77b0012dc736662c",
    "name": "Home"

You can reference the light with the following selectors:

  • `id:d3b2f2d97452`
  • `label:Left Lamp`
  • `group_id:1c8de82b81f445e7cfaafae49b259c71`
  • `group:Lounge`
  • `location_id:1d6fe8ef0fde4c6d77b0012dc736662c`
  • `location:Home`

When using group or location selectors you'll also reference other lights in the same group or location. Take care to correctly encode parameters when using selectors.

Multi-zone and Switch Relay Selectors

Selectors may specify zones which on devices with Zones - the LIFX Z - will act on only those zones.
The same syntax is used to target individual relays on a LIFX Switch. On devices without zones or relays, the zone specifications will be ignored.

Zones/Relays are specified via a |-separated suffix to the device selector: a specific zone or relay is specified by just the number of that zone, between 0 and 255. A zone range is specified as M-N where both M and N are zone numbers between 0 and 255, M <= N, and the endpoint zones are included.

Some examples of such selectors:




All devices, but acts only on Zones/Relays 1, 2, 3 and 4 of devices with zone support


Equivalent to the previous example


All devices in the location with label Kitchen, but acts only on Zones/Relays 1, 5 and 9 of devices with zone support