Skip to content


Query format

The query format starts with the specific items to query for followed by the details of the query.

Qualifier* Range? Search? Sort? Limit? Status?

Qualifiers are separated by comma which acts as a logical OR so that the result contains the combination of all the qualifiers provided.

Results are returned either as a Range or if no range is provided as a Stream. Range results will be the specific start and end requested sorted ascending while Stream will return the current date descending for up to one year.


all users
given trackers [notes] from today as year
given swimlanes [announcements] from today to -2 weeks


Qualifiers identify what data to return. They can be combined together to bring back several different kinds.


qualifier1, qualifier2, ...


Qualifier Definition
all users Return all users
given users [<uid>|<email>|$context,*] Just specific users
given author [<uid>|<email>|$context,*] Just specific authors
current user The current user
current user [cohort|program|following|followers] Users based on their relation to the current user
given|except groups [<uid>|<handle>,*] Including or excluding specific groups
given|except user-labels [<handle>,*] Users with a specific label
given programs [<uid>|<handle>,*] Users who are in a specific program instance
given program-kind [<uid>|<handle>,*] Users that have taken a program kinds
given program-kind-active [<uid>|<handle>,*] Users currently active in a program kinds
given cohorts [<uid>,*] Specific cohorts
all swimlanes All swimlanes
given|except swimlanes [<uid>|<handle>,*] Specific swimlanes
given shares [<uid>,*] Specific global swimlane shares
given|except dispatch-labels [..handle list] Dispatch labels

Client side replacements for uid / email lists: * $user = the user being displayed * $span = a time span if applicable * $cohort|$program = cohort or program id * $start|$end = start or end date if applicable * $date = anchor date for a view

Server side replacements for uid / email lists: * $context = the logged in user


Range specifies the time frame to retrieve. If not provided it returns from today backwards up to either the limit or one year.


from [date] to [date]
from [date] to [measure] [period]
from [date] as [period]
from [measure] to [measure] [period]
from today|past|future|all time
  • Measures: +/- number
  • Dates: YYYY-MM-DD (2020-08-01) or YYYY-MMM-DD (2020-Aug-1) or YYYY-MMM (2020-Aug) or today
  • Periods: day, week, isoWeek, month, year
  • Periods can be plural for greater readability


from today as week
from 2020-01-01 as month
from today to +3 weeks
from -1 to +6 months
from all time


By default public and org security are returned. To retrieve other security levels provide a security clause. Note that in user mode the security clause will be overridden by the actual permission level.

given security [..opts]
all security
opts: public, private, admin, org


Events - filter by dispatch event status.

given events Events* Payload? [..user|email list]
Events: answer|confirm|like|bookmark|
Payload: yes, no, undecided


given event participant [$context] 

Search allows the query to narrow results based on some criteria.

where [entity] [operator] "literal" [conjunction]?
entity: body | state
operator: contains, starts, ends, is, not
conjunction: and | or


Sort the resulting dispatches either ascending or descending. Range defaults to ascending while stream defaults to descending.

asc|desc created|updated|when


Limit the number of returned records. Note that many UI components have a default limit so this can be used to raise the number of records returned.

limit [Number]


Return dispatches with a specific status.

status in [active, draft]

More examples

all swimlanes
all users from today to +7 days
all users from -7 to +7 days
all users from today as day
given labels[public]
all users where body is "hi"