Contact usRequest a demo

Analytics data API

This is a preview feature. It may be subject to change or removal with no further notice.

To enable preview features, set com.unblu.platform.enablePreview to true.

For more information on preview features, refer to the Unblu release policy.

The analytics data API lets external applications consume structured key performance indicator (KPI) data. It does so by exposing the individual records behind Unblu’s analytics KPIs. As a rule, the API returns one record per underlying event. Where the analytics dashboards show aggregated figures, the data API returns the underlying records those figures are calculated from. You use it to extract the records into an analytics system of your own (see Extracting the records).

For the endpoints, their request and response formats, and the field-level schema of each record, refer to the Unblu web API reference.

Why a dedicated API

External applications could in principle read the analytics data straight from the analytics database. Unblu doesn’t expose the database directly because running unoptimized queries could degrade Unblu’s overall performance. The analytics data API instead provides stable, structured access to the same data, independently of how it’s stored.

Record properties

Whatever KPI you query, the records share these properties:

  • Immutable: once written, a record never changes.

  • Append-only: new records are only ever added; existing ones are left untouched.

  • Fine-grained: records aren’t pre-aggregated: each one captures a single underlying event, not a rolled-up total.

  • Enriched: each record carries contextual information beyond the raw event.

  • Denormalized: related entities are embedded in the record with their display names, not just their IDs (for example, an agent appears with their name), so you can read the data without extra lookups.

  • Backend-independent: a record has the same structure whether the data is stored in BigQuery or PostgreSQL.

Beyond the KPI-specific fields documented in the reference, every record carries the following two fields:

  • id: the record’s unique identifier.

  • eventTimestamp: a UTC timestamp marking when the underlying event was recorded. It’s the only field you can filter and sort records by.

    Unblu creates a record once the event it captures is complete. For events that span a period of time, such as a call or a visitor’s wait for an agent, the record therefore only exists once the period has ended. For these events, eventTimestamp marks the period’s end, not its start.

    Each KPI is backed by a different event, so what exactly eventTimestamp marks depends on the KPI (see Available KPIs).

Available KPIs

The API exposes these KPIs, each with its own search endpoint. Each entry lists what a record represents, the webhook event that corresponds to it, and the search endpoint:

To be notified as these events occur instead of polling a search endpoint, subscribe to the corresponding webhook.

Extracting the records

The search endpoints are batch extraction endpoints, not query endpoints. You use them to copy the records into an analytics system of your own. That’s where you then analyze the data. The API therefore offers no filters beyond eventTimestamp: selecting records by their content is part of that analysis.

To extract a KPI’s records, call its search endpoint with a filter on a range of eventTimestamp values. The results are paginated, so a range may take multiple requests to retrieve in full. To extract incrementally, use contiguous ranges that end in the past: they yield each record exactly once. This works because eventTimestamp marks the event’s end. A window on a start timestamp would miss records whose period was still running when the window was fetched.

Once you’ve extracted the records to your analytics system, you can run analyses on the event-specific data in the records. For example, to analyze calls by when they started rather than when they ended, filter the extracted call records by their start timestamp.

Relationship to the analytics dashboards

The analytics dashboard KPIs are aggregations of these same records: the count-based KPIs as counts, the time-based KPIs as averages. They don’t map to the API one to one. The dashboards' Average reservation time KPI, for example, is a time-based average of the reservation records within Queue interactions, so it has no dedicated search endpoint.

See also