> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.app/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": [...]
  }
}
```

<Note>
  Categories are automatically limited to the top 10 most frequent values. Less frequent values are grouped into "other".
</Note>

## 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
}
```

<Tip>
  Set `includeTimeSeries: false` to reduce response size when you only need aggregated statistics.
</Tip>

## 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

<Tip>
  * 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
</Tip>

## 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
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:
                    $ref: '#/components/schemas/object_5a1767ed'
                required:
                  - success
                  - data
                additionalProperties: false
        default:
          $ref: '#/components/responses/error'
      security:
        - Authorization: []
components:
  schemas:
    object_5a1767ed:
      type: object
      properties:
        key:
          type: string
        type:
          $ref: '#/components/schemas/S_194a6ca5'
        average:
          type: number
        sum:
          type: number
        min:
          type: number
        max:
          type: number
        counts:
          type: object
          additionalProperties:
            type: number
        timeSeries:
          $ref: '#/components/schemas/array_44bed485'
        totalDataPoints:
          type: number
      required:
        - key
        - type
        - totalDataPoints
      additionalProperties: false
    S_194a6ca5:
      anyOf:
        - type: string
          enum:
            - numeric
        - type: string
          enum:
            - categorical
    array_44bed485:
      type: array
      items:
        $ref: '#/components/schemas/ts_value_convoid_988402'
    message_11569e:
      type: object
      properties:
        message:
          type: string
      required:
        - message
      additionalProperties: false
    ts_value_convoid_988402:
      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
  responses:
    error:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              issues:
                type: array
                items:
                  $ref: '#/components/schemas/message_11569e'
            required:
              - message
              - code
            additionalProperties: false
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````