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


Qualifier Definition
given trackers [...] Return specific trackers
except trackers [...] Return all trackers except the specific trackers
given tracker-group [...] Return all trackers from a specific group
no trackers Return dispatches without trackers
.. on user|swimlane Narrow the above to just users or just swimlanes


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"

given events bookmark [$context]