Most API endpoints support filtering to retrieve or edit only a subset of resources that match a certain criteria, such as:

  • Filtering actions by Thng ID.
  • Filtering Thngs by product ID.
  • Find products that are named 'x'.
  • Find places tagged 'ACME Inc'.



Please note that any update or delete operations using filters are limited to 500 resources. If more than 500 resources match the specified filter, an error will be returned and no resource will be modified.

To modify a large number of resources, paginate them and carry out the desired operation on each page of items. This can be achieved using the SDKs.

Explicit ID-based Filtering

Many API endpoints allows to explicitly send the IDs of certain resources that should be returned. This is particularly useful when one wants to edit in bulk a set of resources (e.g. update the name of a few Thngs). To explicitly select a few Thngs, one should use the ?ids=X, where X is a list of (existing) URL-encoded comma-separated resource IDs. For example, if one wants to update the name of multiple products by id one could use the following request:

PUT /products?ids=:productId1,:productId2,:productId3
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ProductDocument (subset)
curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT '' \
  -d '{
    "name": "Updated name"
const ids = [

const payload = { name: 'Updated name' };
const params = { ids: ids.join(',') };

user.product().update(payload, { params })
Iterator<PVector<Thng>> iterator = apiManager.thngService().iterator()
    .filter("name=Original name").execute();



The filter query string must be URL-encoded.

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

    "id": "U2E9hmyCVg8atpRwwXgTqcrt",
    "name": "Updated name",
  }, {
    "id": "UFEsATFh63PhhqwaRhEdeAek",
    "name": "Updated name",
  }, {
    "id": "UFcMeG6e5gwhWGSsE4gccKfk",
    "name": "Updated name",

Query-based Filtering

Filters are used to retrieve or bulk edit multiple resources that match a particular filter. You can therefore append ?filter=X to the endpoint URL when doing a GET, PUT, or DELETE operation (where X is a query). Note that the ?filter is mutually exclusive with ?ids where a list of existing resource IDs must be given.



Filters that include multiple conditions (e.g: name=test&tags=device) are evaluated from left to right, so name is matched, then the resulting results are filtered for tags.

Query Structure

Our queries are of the form X AND Y AND Z only, and we do not support the OR operator. Other operators supported are:



The available operators vary depending on the type of resource being filtered. See Available Fields for more information about resource filterable fields.



Encoded Format








Ranges (inclusive)



Ending wildcard (starts with)








Less or equal






Greater or equal



Not. Inverts another filter clause. For example, to find resources without the 'test' tag:



Simple Field Filtering Examples

You can search for any field of a given Thng or product.

Most API endpoints support the ?filter=X query parameter that allows to limit the results returned by a query to only the resources that match a certain criteria set (defined by the query X). See the following examples:

  • /thngs?filter=name%3Dtv
    Find all Thngs named tv

  • /products?filter=name%3Dmilk%2Cegg
    Find all products named milk OR egg

  • /thngs?filter=name%3Dsensor*
    Find all Thngs whose name start with sensor

  • /thngs?filter=tags%3DUK
    Find all Thngs that contain the tag UK

  • /thngs?filter=tags%3DUK%2Cshipped
    Find all Thngs that contain the tags UK OR shipped

  • /thngs?filter=tags%3DUK%26tags%3Dshipped
    Find all Thngs that contain the tag UK AND shipped

  • /actions/all?filter=timestamp%3E1477323564350
    Find all actions created after 1477323564350 (timestamp is larger than 1477323564350)

  • /actions/all?filter=timestamp%3D1477323564350..1478871333924
    Find all actions by timestamp created after 1477323564350 and before 1478871333924 (inclusive).

Available Fields

Depending on the resource being filtered, a discrete set of filter fields are available. These are described for each resource's respective page in the API Reference after the resource's main definition.

For example, for the ThngDocument resource type.

Filtering in evrythng.js

Filtering in evrythng.js works the same way as parameters, with some additional helpers:

// Simple string - same as the REST API

// Object notation
const filter = { name: 'Actuator,Sensor', tags: 'shipped' };

// Find by identifiers key
const factoryId = 'f2323786';
const filter = `identifiers.gs1:414=${factoryId}`;

Updated about a year ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.