Docs »

Data Queries

A text-based grammar for querying and transforming data to drive visualizations

Data queries are a purpose-built, text-based query language to retrieve, transform, and format data for visualizations.

These textual queries are very simple to automate in automations, dashboard widgets, or the API.

A data query is a collection of key:value pairs.

Every query must include a type: key:


Additional keys are available depending on the type of data being requested.

A format: key prepares the response for different visualizations:



Type Description
attachment.manifest Iterates and filters the manifest of attachment archives (e.g. ZIP).
automation.invoke Invoke a custom data.query automation.
calendar.availability Aggregate any number of matching calenders to display availability over a date range by hour or day Return events and synthesized recurring events for the given calendars grouped into days
classifier.prediction Return a predicted classification for the given text using the given classifier
gpg.keyinfo Return details about a PGP public key
metrics.timeseries Aggregates metrics statistics over a date range
platform.extensions Return a filterable and pageable list of plugin extensions for a given point
record.fields Return a filterable and pageable list of fields from a record type
record.types Return a filterable and pageable list of record types
ui.icons Return a filterable and pageable list of icons
usage.behaviors Return historical usage data for bot behaviors (e.g. uses, avg. runtime, and total runtime over time)
usage.snippets Return historical usage data for snippets (e.g. uses by worker over time)
worklist.geo.points Return geolocation data from worklist records
worklist.metrics Return computed metrics based on worklist data (e.g. ‘average ticket first response time over the past year’)
worklist.records Retrieve record dictionaries with a search query
worklist.series Return series-based data from any worklist (e.g. tickets created by month by status)
worklist.subtotals Run aggregate functions to categorize matching worklist records
worklist.xy Plot two-dimensional data to visualize clusters or correlations
sample.* Return simulated data
custom Fetch custom data from a bot behavior

Running data queries

Data queries may be utilized in several features.


As an administrator, you can test data queries from Setup » Developers » Data Query Tester.

Dashboard widgets

Data queries can be used to build visualizations on dashboards.

Bot behaviors

All bot behaviors can use the Execute » Data Query action to run a data query and retrieve the results.

This is a much simpler way to exchange information between bots and APIs.


Data queries can be run from the API using the /data/query endpoint.

For a GET the query should be provided in the q query parameter.

For a POST the query should be provided as text in the HTTP request body.

The results will always be in JSON format. This is now the recommended way to extract data from worklists and bots for use in other applications.

Data is returned in JSON format.