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.

Selector

Returns

all

All lights belonging to the authenticated account

label:[value]

Lights that match the label.

id:[value]

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

group_id:[value]

The lights belonging to the group with the given ID

group:[value]

The lights belonging to the groups matching the given label

location_id:[value]

The lights belonging to the location matching the given ID

location:[value]

The lights belonging to the locations matching the given label

scene_id:[value]

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:

Selector

Returns

all|1|2|3|4

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

all|1-4

Equivalent to the previous example

location:Kitchen|1|5|9

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