Run an analytics query | Speechify API

curl -X POST https://api.speechify.ai/v1/agents/analytics/query \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "metric": {
    "agg": "count"
  }
}'

{
  "metric": {
    "agg": "count",
    "field": "",
    "rate_predicate": {
      "field": "",
      "op": "eq",
      "value": null
    }
  },
  "group_by": [
    "call_status"
  ],
  "bucket": "none",
  "series": [
    {
      "total": 125,
      "group": {},
      "points": [
        {
          "t": "2024-04-01T00:00:00Z",
          "value": 125
        }
      ]
    }
  ],
  "meta": {
    "group_count": 1,
    "truncated": false
  },
  "previous": {
    "series": [
      {
        "total": 110,
        "group": {},
        "points": [
          {
            "t": "2024-03-01T00:00:00Z",
            "value": 110
          }
        ]
      }
    ]
  }
}

Run one tenant-scoped aggregation over the workspace’s conversations and post-call evaluations — the query that powers a single dashboard widget. Every chart type is a different shape of this request: a number card omits group_by and time.bucket; a line chart sets a time.bucket; bar / column / donut set group_by; a table sets several group_by dimensions.

metric is the value each group/bucket reduces to (count, or an avg / sum / min / max over a numeric field, or a rate whose numerator is rate_predicate). group_by and filters reference dimension keys from GET /v1/agents/analytics/dimensions; an unknown dimension, metric, or operator is rejected. compare_to_previous returns the same query for the immediately preceding period. The number of breakdown groups is capped by breakdown_limit; meta.truncated reports when groups were dropped.

Run one tenant-scoped aggregation over the workspace's conversations and post-call evaluations — the query that powers a single dashboard widget. Every chart type is a different shape of this request: a number card omits `group_by` and `time.bucket`; a line chart sets a `time.bucket`; bar / column / donut set `group_by`; a table sets several `group_by` dimensions. `metric` is the value each group/bucket reduces to (`count`, or an `avg` / `sum` / `min` / `max` over a numeric field, or a `rate` whose numerator is `rate_predicate`). `group_by` and `filters` reference dimension keys from `GET /v1/agents/analytics/dimensions`; an unknown dimension, metric, or operator is rejected. `compare_to_previous` returns the same query for the immediately preceding period. The number of breakdown groups is capped by `breakdown_limit`; `meta.truncated` reports when groups were dropped.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.

metricobjectRequired

The value each group / bucket reduces to.

group_bylist of stringsOptional

Up to 5 groupable dimension keys. Empty for a single-value (number) result.

filterslist of objectsOptional

timeobjectOptional

Time scope + bucketing. Defaults to the last 30 days, the started_at field, no bucketing, and UTC.

compare_to_previousbooleanOptional

When true, also return the same query for the immediately preceding period of equal length.

breakdown_limitintegerOptional

Max number of breakdown groups (default 50, capped at 50). Excess groups are dropped and meta.truncated is set.

Response

The aggregation result.

metricobject

The value each group / bucket reduces to.

group_bylist of strings

bucketenum

serieslist of objects

metaobject

previousobject

The same query over the immediately preceding period.

Errors

400

Bad Request Error

401

Unauthorized Error