Analytics API: Custom Metric Queries

Overview

The Analytics API lets you run custom metric queries against your call data programmatically, without going through the dashboard UI. It's the same underlying data source that powers the Boards widgets described in Observability: Boards, Logs & Analytics. If you want a visual, shareable dashboard and don't need to write queries yourself, Boards is the easier no-code path — this page is for teams building their own reporting on top of the raw data.

Request Structure: AnalyticsQueryDTO & AnalyticsQuery

Send a POST request to /analytics with a queries array. Each entry is an AnalyticsQuery object:

Field	Type	Required	Description
`table`	string (enum)	Yes	The data source to query: `call` or `subscription`
`name`	string	Yes	A unique identifier for the query, used to match results in the response
`operations`	array	Yes	List of aggregation operations to perform
`groupBy`	string (enum)	No	A standard column to group results by
`groupByVariableValue`	array	No	Custom variable keys to group by
`timeRange`	object	No	The time range and step for the query

groupBy & groupByVariableValue

The standard groupBy field accepts one of these values:

type
assistantId
endedReason
analysis.successEvaluation
status

For anything beyond these standard dimensions, use groupByVariableValue to group by custom variable keys extracted during calls — for example, a customer satisfaction score, a lead qualification status, or any other custom KPI your assistant extracts via dynamic variables or structured outputs.

Operations: Aggregations & Columns

Each entry in the operations array is an AnalyticsOperation object:

Field	Type	Required	Description
`operation`	string (enum)	Yes	The aggregation to perform
`column`	string (enum)	Yes	The column to aggregate
`alias`	string	No	Custom name for the result field; defaults to `${operation}${column}`

Aggregation types (operation): sum, avg, count, min, max, history

Available columns: id, cost, duration, concurrency, minutesUsed, and a set of cost-breakdown columns: costBreakdown.llm, costBreakdown.stt, costBreakdown.tts, costBreakdown.transport, costBreakdown.transcriber, costBreakdown.ttsCharacters, costBreakdown.llmPromptTokens, costBreakdown.llmCompletionTokens, costBreakdown.llmCachedPromptTokens, and costBreakdown.analysisBreakdown.summary.

timeRange Configuration

The timeRange object controls the window and granularity of the query:

Field	Type	Description
`start`	date-time	Start of the range. Defaults to 7 days ago
`end`	date-time	End of the range. Defaults to now
`step`	string (enum)	Time bucket size for aggregation. Defaults to the entire range
`timezone`	string	Timezone for the query. Defaults to UTC

Valid step values: second, minute, hour, day, week, month, quarter, year, decade, century, millennium.

Worked Example & Response Format

Example: max concurrency per day over a date range.

curl -X POST 'https://api.sulus.ai/analytics' \
  -H 'Authorization: Bearer $CORE_SYSTEM_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "queries": [{
      "name": "Number of Concurrent Calls",
      "table": "subscription",
      "timeRange": {
        "start": "2026-06-16T18:30:00.000Z",
        "end": "2026-07-17T05:31:10.184Z",
        "step": "day"
      },
      "operations": [{
        "operation": "max",
        "column": "concurrency",
        "alias": "concurrency"
      }]
    }]
  }'

The response is an array of AnalyticsQueryResult objects, one per query in your request, each containing the matching name, the evaluated timeRange, and a result array of grouped values:

[{
  "name": "Number of Concurrent Calls",
  "timeRange": { "start": "...", "end": "...", "step": "day", "timezone": "UTC" },
  "result": [
    { "date": "2026-07-05T00:00:00.000Z", "concurrency": 0 },
    { "date": "2026-07-10T00:00:00.000Z", "concurrency": 1 }
  ]
}]

You can combine groupBy, groupByVariableValue, timeRange, and multiple operations in a single query to build rich, multi-dimensional reports.

Boards: The No-Code Alternative

If your team doesn't want to write and maintain API queries, Boards give you the same underlying data through a visual, drag-and-drop dashboard builder, with support for calculated metrics via formulas. See Observability: Boards, Logs & Analytics for the full Boards walkthrough, including widget types and worked formula examples. Use the Analytics API covered on this page when you want to pull this same data into your own reporting systems or CI/CD pipelines instead.

On this page

Analytics API: Custom Metric Queries