Skip to main content
GET
/
agents
/
{agentId}
/
custom-metrics
/
{metricKey}
/
data
Get metric data and aggregations
curl --request GET \
  --url https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/custom-metrics/{metricKey}/data \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "data": {
    "key": "<string>",
    "type": "numeric",
    "totalDataPoints": 123,
    "average": 123,
    "sum": 123,
    "min": 123,
    "max": 123,
    "counts": {},
    "timeSeries": [
      {
        "ts": 123,
        "value": "<string>",
        "convo_id": "<string>"
      }
    ]
  }
}

​
Overview

Fetches aggregated analytics data for a specific metric within a time range. Returns statistical summaries and optional time-series data points.

​
Numeric Metrics

For number-type metrics, the response includes statistical aggregations: 
{
  "success": true,
  "data": {
    "key": "customer_satisfaction",
    "type": "numeric",
    "average": 8.5,
    "sum": 425,
    "min": 5,
    "max": 10,
    "totalDataPoints": 50,
    "timeSeries": [
      {
        "ts": 1640000000,
        "value": 8,
        "convo_id": "convo_123"
      }
    ]
  }
}

​
Available Aggregations

  • average: Mean value across all data points
  • sum: Total sum of all values
  • min: Minimum recorded value
  • max: Maximum recorded value

​
Categorical Metrics

For boolean, enum, and string types, the response includes count distributions: 
{
  "success": true,
  "data": {
    "key": "sentiment",
    "type": "categorical",
    "counts": {
      "positive": 30,
      "negative": 10,
      "neutral": 10
    },
    "totalDataPoints": 50,
    "timeSeries": [...]
  }
}
Categories are automatically limited to the top 10 most frequent values. Less frequent values are grouped into “other”.

​
Time-Series Data

The timeSeries array provides individual data points with timestamps and conversation IDs: 
// Each time-series point
{
  "ts": 1640000000,        // Unix timestamp (seconds)
  "value": 8,              // Metric value
  "convo_id": "convo_123"  // Associated conversation ID
}
Set includeTimeSeries: false to reduce response size when you only need aggregated statistics.

​
Time Range Examples

​
Last 24 Hours

const now = Math.floor(Date.now() / 1000);
const yesterday = now - (24 * 60 * 60);

const data = await fetch(
  `/v3/agents/{agentId}/custom-metrics/customer_satisfaction/data?startTs=${yesterday}&endTs=${now}`
);

​
Last 7 Days

const now = Math.floor(Date.now() / 1000);
const weekAgo = now - (7 * 24 * 60 * 60);

const data = await fetch(
  `/v3/agents/{agentId}/custom-metrics/nps_score/data?startTs=${weekAgo}&endTs=${now}`
);

​
Current Month

const now = new Date();
const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1);
const startTs = Math.floor(startOfMonth.getTime() / 1000);
const endTs = Math.floor(Date.now() / 1000);

​
Use Cases

  • Dashboard Analytics: Power real-time metric dashboards
  • Trend Analysis: Identify patterns over time
  • Performance Reports: Generate periodic performance summaries
  • Alerts: Trigger notifications based on metric thresholds
  • A/B Testing: Compare metric performance across different periods

​
Performance Tips

  • Use smaller time ranges for faster queries
  • Disable includeTimeSeries when you don’t need individual data points
  • Cache results for frequently accessed date ranges
  • Query during off-peak hours for large historical data requests

​
No Data Response

When no data points exist for the time range: 
{
  "success": true,
  "data": {
    "key": "customer_satisfaction",
    "type": "numeric",
    "totalDataPoints": 0,
    "timeSeries": []
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agentId
string
required

The unique identifier of the agent

​
metricKey
string
required

The key of the metric to retrieve data for

Query Parameters

​
startTs
number
required

Start timestamp (Unix timestamp in seconds)

​
endTs
number
required

End timestamp (Unix timestamp in seconds)

​
includeTimeSeries
boolean
default:true

Response

Successful response

​
success
boolean
required
​
data
object
required