Observability: Boards, Logs & Analytics

Overview

Sulus gives you three ways to see what your assistants are actually doing: custom analytics dashboards (Boards), the raw logs behind every call, API request, and webhook delivery, and a set of downloadable call artifacts and a programmatic Analytics API for teams that want to build their own reporting on top of the same data.

Boards let you build a custom analytics dashboard from several widget types:

Each widget is configured with a data source (e.g., Calls), a metric (e.g., Count of Call ID), an optional Group By dimension, and a time range. Line charts can overlay a second metric; bar and line charts support Group By Time (minute, hour, day, week, month) for trend granularity.

A global time-range filter and granularity setting at the top of the dashboard updates every widget on the board simultaneously, so you don't have to configure the time window widget by widget.

Once added, widgets can be arranged on the dashboard grid: drag to reposition using the widget header handle, and resize by dragging the bottom-right corner. A common layout pattern is KPI text widgets at 1–2 grid columns wide and charts at 3–4 columns wide.

Boards also support calculated metrics — formulas that combine multiple underlying queries into a single derived number, written in Math.js-style syntax.

To build one: add a Text widget, enable Formula Mode, define one or more named queries (each with its own metric and optional filter), then write a formula referencing each query name wrapped in {{ }}.

Common formula examples:

// Booking Conversion Rate (percentage)
({{totalBookings}} / {{totalCalls}}) * 100

// Cost Per Call
{{totalCost}} / {{totalCalls}}

// Average Cost Per Minute
{{totalCost}} / ({{totalMinutes}} / 60)

// Success Rate
({{successfulCalls}} / {{totalCalls}}) * 100

Example walkthrough for a booking conversion rate metric:

1. Add a Text widget named "Booking Rate (%)" and enable Formula Mode
2. Add Query 1 — name it totalBookings, metric: Count of Call ID, filter: Status = "booking_confirmed"
3. Add Query 2 — name it totalCalls, metric: Count of Call ID (no filter)
4. Enter the formula ({{totalBookings}} / {{totalCalls}}) * 100
5. Preview to validate, then add to the board

Query names must match exactly between your queries and your formula, or you'll get a formula syntax error.

The dashboard's Observe section provides three distinct log views, each for a different debugging purpose:

When troubleshooting an issue, it helps to have on hand: the call ID and timestamp from Call Logs, a description of expected vs. actual behavior, the relevant configuration (with API keys removed), and any error messages shown in the logs.

For phone calls, Sulus generates a set of retrievable artifacts controlled by your assistant's artifactPlan: recordings, transcripts, detailed logs, and (when enabled) SIP packet captures (PCAP).

These are retrievable via API, either as URLs on the call object or through dedicated authenticated download endpoints that respond with a short-lived signed URL:

curl -L \
  -H "Authorization: Bearer $CORE_SYSTEM_API_KEY" \
  -o recording.wav \
  https://api.sulus.ai/call/<CALL_ID>/stereo-recording

Because signed URLs expire, always request a fresh one from the API rather than caching the redirect target.

For teams that want programmatic access to the same data shown on Boards, a separate Analytics API endpoint is available for querying call history and usage data directly, without going through the dashboard UI. You can adjust the requested time range and step (hour, day, week) to review usage patterns historically — the same underlying data source that powers dashboard widgets and historical concurrency views.

In summary, use Boards when you want a visual, shareable dashboard with calculated KPIs; use the Observe logs (Call, API, Webhook) when you're debugging a specific issue; use call artifact endpoints when you need the raw recording, transcript, or log file for a single call; and use the Analytics API when you want to pull this data into your own reporting systems.