Skip to main content
GET
/
agents
/
{agentId}
/
custom-metrics
/
data
Get all metrics data and aggregations
curl --request GET \
  --url https://eu-gcp-api.vg-stuff.com/v3/agents/{agentId}/custom-metrics/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 all metrics of an agent within a specified time range. This endpoint is ideal for dashboard overviews and comprehensive reporting.

​
Bulk Analytics

Instead of making individual requests for each metric, get all metric data at once: 
// Single request for all metrics
const allMetrics = await fetch(
  `/v3/agents/{agentId}/custom-metrics/data?startTs=${startTs}&endTs=${endTs}`
);

​
Response Format

Returns an array with aggregated data for each metric: 
{
  "success": true,
  "data": [
    {
      "key": "customer_satisfaction",
      "type": "numeric",
      "average": 8.5,
      "sum": 425,
      "min": 5,
      "max": 10,
      "totalDataPoints": 50
    },
    {
      "key": "sentiment",
      "type": "categorical",
      "counts": {
        "positive": 30,
        "negative": 10,
        "neutral": 10
      },
      "totalDataPoints": 50
    },
    {
      "key": "issue_resolved",
      "type": "categorical",
      "counts": {
        "true": 45,
        "false": 5
      },
      "totalDataPoints": 50
    }
  ]
}

​
Time-Series Control

By default, time-series data is not included to keep responses lightweight. Enable it when needed: 
GET /v3/agents/{agentId}/custom-metrics/data?startTs=1640000000&endTs=1640100000&includeTimeSeries=true
Setting includeTimeSeries: true significantly increases response size. Only enable when you need individual data points for each metric.

​
Use Cases

​
Dashboard Overview

Perfect for displaying all KPIs in a single dashboard view: 
// Fetch all metrics for today
const today = new Date();
today.setHours(0, 0, 0, 0);
const startTs = Math.floor(today.getTime() / 1000);
const endTs = Math.floor(Date.now() / 1000);

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

// Display each metric in dashboard cards
dashboardData.data.forEach(metric => {
  if (metric.type === 'numeric') {
    displayNumericCard(metric.key, metric.average, metric.sum);
  } else {
    displayCategoricalChart(metric.key, metric.counts);
  }
});

​
Weekly Reports

Generate comprehensive weekly performance reports: 
const now = Math.floor(Date.now() / 1000);
const weekAgo = now - (7 * 24 * 60 * 60);

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

// Generate PDF or email report
generateWeeklyReport(weeklyReport.data);

​
Comparative Analysis

Compare multiple metrics side-by-side: 
const metricsData = await fetchAllMetrics();

// Find correlations between metrics
const satisfaction = metricsData.find(m => m.key === 'customer_satisfaction');
const resolution = metricsData.find(m => m.key === 'issue_resolved');

analyzeCorrelation(satisfaction, resolution);

​
Performance Considerations

Optimization Tips:
  • Keep time ranges reasonable (7-30 days for routine queries)
  • Cache results for frequently accessed date ranges
  • Use pagination if you have many metrics (50+)
  • Set includeTimeSeries: false unless you specifically need it
  • Schedule large historical queries during off-peak hours

​
Response Size

Response size varies based on:
  • Number of configured metrics
  • Time range (more data points = larger response)
  • includeTimeSeries setting
  • Complexity of categorical distributions
Typical sizes:
  • 10 metrics, 24 hours, no time-series: ~5-10 KB
  • 20 metrics, 7 days, no time-series: ~15-30 KB
  • 20 metrics, 7 days, with time-series: ~500 KB - 2 MB

​
Empty Results

When no data exists for any metrics in the time range: 
{
  "success": true,
  "data": []
}

​
Integration Example

// TypeScript example
interface MetricData {
  key: string;
  type: 'numeric' | 'categorical';
  average?: number;
  sum?: number;
  min?: number;
  max?: number;
  counts?: Record<string, number>;
  totalDataPoints: number;
}

async function fetchAgentMetrics(
  agentId: string,
  startTs: number,
  endTs: number
): Promise<MetricData[]> {
  const response = await fetch(
    `/v3/agents/${agentId}/custom-metrics/data?startTs=${startTs}&endTs=${endTs}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  const result = await response.json();
  return result.data;
}

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

Query Parameters

​
startTs
number
required

Start timestamp (Unix timestamp in seconds)

​
endTs
number
required

End timestamp (Unix timestamp in seconds)

​
includeTimeSeries
boolean
default:false

Response

Successful response

​
success
boolean
required
​
data
object[]
required