Querying Options

Query string parameters can be used to filter down a result set and generally format API responses.

In general, most complex querying & formatting is difficult to cache and therefor a burden on both client bandwidth and server processing. For this reason, we encourage biasing your decisions in favor of avoiding these features where possible. As we begin to enforce rate limiting in the future, you may find that complex queries & formatting requests count against your limit in a way that more basic requests do not.


?limit (integer): Limit the number of results returned on a GET query. The default limit is 20, and can be overridden up to 100.

?page (integer): Specify the page number for results returned on a GET query. The default page number is 1.


?sort (string): Specify an API attribute to sort results by when performing a GET query. Optionally, an array of attributes to sort by can be defined like so: ?sort[]=attribute1&sort[]=attribute2. By default, all result sets are sorted by a resource's primary ID.

?direction (string): Specify a direction to sort results by: asc or desc. This direction should corresponding to the attribute name provided in sort and can also take the form of an array. By default, all result sets are sorted ascending.

Operator Prefixes

Operators may be used when performing a GET query, providing an ample amount of search & filtering capability. Equals prefixes represent an exact match; contains, starts-with, and ends-with prefixes represent partial match searches.

  • ?attribute=value: attribute equals value
  • ?not-attribute=value: attribute does not equal value
  • ?contains-attribute=value: attribute contains value
  • ?not-contains-attribute=value: attribute does not contain value
  • ?starts-with-attribute=value: attribute starts with value
  • ?ends-with-attribute=value: attribute ends with value
  • ?min-attribute=5: attribute is at least 5
  • ?max-attribute=10: attribute is no more than 10

Multiple Conditions

Multiple conditions are assumed to be joined by AND. For example: ?attribute1=1&attribute2=999 is the equivalent of asking the API to give you all results where attribute1 equals 1 AND attribute2 equals 999. There is currently no way to create OR conditions across attributes when querying the API dynamically.

Within one attribute, multiple values can be separated by a pipe to create OR conditions. For example: ?attribute1=1|2 is the equivalent of asking the API to give you all results where attribute1 equals 1 OR 2.

Combining these concepts, you can pass a query such as ?attribute1=1|2&attribute2=999 to ask the API for all results where (attribute1 equals 1 OR 2) AND (attribute2 equals 999).

Limiting Returned Attributes

?attributes can be used to limit the attributes returned in a GET request, usually to help save network bandwidth and/or simplify caching. For example: ?attributes=first,second will ensure that only the attributes named first and second, respectively, are returned in the result set.

Relational Data

?related allows for querying resources which are related to the current GET request. For example: ?related=RelatedResource will join in the RelatedResource object. It is strongly encouraged to avoid using this option unless absolutely necessary. It is not easy to cache and is therefore a burden on both bandwidth and processing. If you need to make multiple requests, this parameter is useful for reducing the number of requests and saving overall request time. To see the available relations on a resource, you can look at the implementation notes for a GET request of that resource in the Resources section. For example, the relations for a workspace are listed here.

Timezone Conversion

By default, all user-centric datetimes are output in UTC. It is possible to ask the API for these datetimes in the timezone of the current user. To do so, specify a ?timezone with either a numerical offset or a string value from the Olson database. For example: ?timezone=America/New_York. To use datetimes in the timezone of the current authenticated you would use: ?timezone=user.