COcommonroom
Analytics

Query analytics metrics

Computes catalog metrics for the reps on a set of teams, as one total or broken down by groupBy, over a window (range, or start and end) or on a date (asOf, snapshot metrics only). Every request names who it covers with personaIds (teams, including their sub-teams), memberIds (reps), or both. Admins can query every team, and managers with Editor permission the teams they manage and their sub-teams. A team or rep outside the caller's scope fails the whole request.

groupBy=action lists the actions behind repAction metrics, newest first, in pages: pass meta.nextCursor back as cursor for the next page. Other results come whole in one response. The token must grant analytics:read (or the encompassing read scope); action rows carry contact emails and Salesforce ids, so groupBy=action also needs contacts:read.

Example request, completed tasks per rep on two teams over the last 7 days, as in the app:

curl --get 'https://api.commonroom.io/api/v2/analytics/query' \
  --header "Authorization: Bearer $COMMON_ROOM_API_TOKEN" \
  --data-urlencode 'metrics=tasksMarkedDone' \
  --data-urlencode 'groupBy=rep' \
  --data-urlencode 'personaIds=p_31' \
  --data-urlencode 'personaIds=p_32' \
  --data-urlencode 'range=P7D' \
  --data-urlencode 'timeZone=America/Los_Angeles'
get/analytics/query

Request

Query parameters

metricsstring[] required

Metric keys from the catalog, repeated (metrics=a&metrics=b).

groupBystring[]

Dimension keys, repeated. Every metric must support the combination. Omit for one row covering everyone.

rangestring

ISO 8601 duration of at most a year. Durations of a day or longer end at the start of tomorrow in timeZone, like the app's presets; durations in hours or minutes end now. Excludes start, end and asOf.

startstring date-time

Inclusive window start, ISO 8601 with offset. URL-encode a + offset as %2B. Requires end.

endstring date-time

Exclusive window end, in the same format as start. At most a year after start.

asOfstring date

A date for a point-in-time query. Only metrics with snapshot temporality accept it.

timeZonestring

IANA time zone for range, and the zone start and end are reported in. Not accepted with asOf.

personaIdsstring[]

Teams to report on, repeated, including their sub-teams.

memberIdsstring[]

Reps to report on by contact id, repeated. With personaIds, narrows those teams to these reps.

segmentIdsstring[]

Only actions taken in these segments, repeated. repAction metrics only.

sepDestinationsstring[]

Only sends to these destinations, repeated; the catalog lists the workspace's. repAction metrics only.

repMetricsstring[]

Only actions that count toward one of these rep metrics, repeated. repAction metrics only.

sortstring

A requested metric or a column of a grouped dimension. Nulls sort last. Action rows sort only by startedAt.

direction'asc' | 'desc'

Sort order. Only with sort.

limitinteger

Keep the first N rows after sorting. Only with sort, except with groupBy=action, where it is the page size (default 25). meta.totalRows gives the count before the limit.

cursorstring

The meta.nextCursor of an earlier groupBy=action response, for the next page.

Response

OK

successtrue required
dataobject[] required

One object per row: the grouped dimensions' columns, then the requested metrics, then snapshotDate when a snapshot metric is requested. Each value is computed for the requested grouping, so adding rows doesn't reproduce a coarser total; request the coarser groupBy instead.

Example response

{
  "meta": {
    "scope": {
      "teams": [
        {
          "id": "p_31"
        }
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.