> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Metric Data
> Retrieve aggregated data and analytics for a specific metric
## 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```javascript theme={null}
// 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
```javascript theme={null}
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
```javascript theme={null}
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
```javascript theme={null}
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:
```json theme={null}
{
"success": true,
"data": {
"key": "customer_satisfaction",
"type": "numeric",
"totalDataPoints": 0,
"timeSeries": []
}
}
```
## OpenAPI
````yaml GET /agents/{agentId}/custom-metrics/{metricKey}/data
openapi: 3.0.3
info:
title: Convocore OpenAPI
description: Full API reference for Convocore
version: 1.0.4
servers:
- url: https://eu-gcp-api.vg-stuff.com/v3
description: EU Node.js API server
- url: https://na-gcp-api.vg-stuff.com/v3
description: NA Node.js API server
security: []
paths:
/agents/{agentId}/custom-metrics/{metricKey}/data:
get:
tags:
- Custom Metrics
summary: Get metric data and aggregations
description: >-
Retrieves aggregated data for a specific metric within a time range.
Returns averages and sums for numeric metrics, and counts for
categorical metrics. Also includes time-series data points.
operationId: customMetrics-getMetricData
parameters:
- name: agentId
in: path
required: true
schema:
type: string
description: The unique identifier of the agent
- name: metricKey
in: path
required: true
schema:
type: string
description: The key of the metric to retrieve data for
- name: startTs
in: query
required: true
schema:
type: number
description: Start timestamp (Unix timestamp in seconds)
- name: endTs
in: query
required: true
schema:
type: number
description: End timestamp (Unix timestamp in seconds)
- name: includeTimeSeries
in: query
required: false
schema:
type: boolean
default: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
key:
type: string
type:
anyOf:
- type: string
enum:
- numeric
- type: string
enum:
- categorical
average:
type: number
sum:
type: number
min:
type: number
max:
type: number
counts:
type: object
additionalProperties:
type: number
timeSeries:
type: array
items:
type: object
properties:
ts:
type: number
value:
anyOf:
- type: string
- type: number
- type: boolean
convo_id:
type: string
required:
- ts
- value
- convo_id
additionalProperties: false
totalDataPoints:
type: number
required:
- key
- type
- totalDataPoints
additionalProperties: false
required:
- success
- data
additionalProperties: false
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````