Custom Metrics

Query custom metrics collected from your agent sessions. Metrics are scoped to your organization automatically. Use these endpoints to retrieve metric names, time-series data, aggregated totals, and daily breakdowns.

Authentication#

All API requests require an API key. Generate one from your account settings.

Include the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Authorization#

Requires organization admin or owner role. Requests from users without the required role return 403 Forbidden.

Base URL#

https://api.voicerun.com/v1/custom-metrics

List Metric Names#

Returns the distinct metric names available for your organization.

GET /v1/custom-metrics/names

Query Parameters#

Example Request#

GET /v1/custom-metrics/names?agentId=agent_xyz

Example Response#

{
  "data": [
    "booking_attempt",
    "booking_completed",
    "cancellation_attempt",
    "cancellation_completed",
    "faq_query",
    "sessions_handled"
  ]
}

Get Aggregate Metrics#

Retrieve summed totals for one or more metrics over a date range. Omit metricNames to query all available metrics.

GET /v1/custom-metrics/aggregate

Query Parameters#

Example Request#

GET /v1/custom-metrics/aggregate?metricNames=booking_attempt,booking_completed&agentId=agent_xyz&startDate=2025-04-01&endDate=2025-04-14

Example Response (no groupBy)#

{
  "data": {
    "booking_attempt": 5,
    "booking_completed": 3
  }
}

Example Request with groupBy#

GET /v1/custom-metrics/aggregate?startDate=2025-04-01&endDate=2025-04-14&groupBy=company_id

Example Response (with groupBy)#

{
  "data": [
    {
      "company_id": "abc",
      "metrics": {
        "booking_attempt": 3,
        "booking_completed": 2,
        "sessions_handled": 5
      }
    },
    {
      "company_id": "def",
      "metrics": {
        "booking_attempt": 2,
        "booking_completed": 1,
        "sessions_handled": 4
      }
    }
  ]
}

Example: FAQ Topic Breakdown#

Use groupBy=topic to see which FAQ topics are most common:

GET /v1/custom-metrics/aggregate?metricNames=faq_query&agentId=agent_xyz&startDate=2025-04-01&endDate=2025-04-14&groupBy=topic

{
  "data": [
    { "topic": "pricing", "metrics": { "faq_query": 12 } },
    { "topic": "opening_hours", "metrics": { "faq_query": 8 } },
    { "topic": "cancellation_policy", "metrics": { "faq_query": 5 } }
  ]
}

Get Daily Metrics#

Retrieve a daily breakdown of one or more metrics over a date range. Each entry contains the date and summed metric values for that day.

GET /v1/custom-metrics/daily

Query Parameters#

Example Request#

GET /v1/custom-metrics/daily?metricNames=sessions_handled,booking_attempt,booking_completed&agentId=agent_xyz&startDate=2025-04-01&endDate=2025-04-07

Example Response#

{
  "data": [
    {
      "date": "2025-04-01",
      "metrics": {
        "sessions_handled": 12,
        "booking_attempt": 5,
        "booking_completed": 3
      }
    },
    {
      "date": "2025-04-02",
      "metrics": {
        "sessions_handled": 8,
        "booking_attempt": 4,
        "booking_completed": 2
      }
    },
    {
      "date": "2025-04-03",
      "metrics": {
        "sessions_handled": 15,
        "booking_attempt": 7,
        "booking_completed": 6
      }
    }
  ]
}

Get Timeseries#

Retrieve time-series data for a single metric with type-appropriate aggregation (sum for counters, average for gauges, p95 for histograms).

GET /v1/custom-metrics/timeseries

Query Parameters#

Example Request#

GET /v1/custom-metrics/timeseries?metricName=booking_attempt&startDate=2025-04-01T00:00:00Z&endDate=2025-04-02T00:00:00Z&step=1h

Example Response#

{
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": { "metric_name": "booking_attempt" },
        "values": [
          [1743465600, "2"],
          [1743469200, "1"],
          [1743472800, "3"]
        ]
      }
    ]
  }
}

Get Tags#

Discover user-defined tag keys and their values for your metrics. System labels (like organization_id, agent_id, session_id) are excluded.

GET /v1/custom-metrics/tags

Query Parameters#

Example Response#

{
  "data": {
    "origin": ["phone", "web"],
    "company_id": ["abc", "def"],
    "branch_id": ["branch-1", "branch-2"]
  }
}

Get Session Metrics#

Retrieve all custom metrics recorded for a specific session.

GET /v1/custom-metrics/sessions/:sessionId

Path Parameters#

Example Request#

GET /v1/custom-metrics/sessions/session_abc123

Example Response#

{
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "metric_name": "booking_completed",
          "agent_id": "agent_xyz",
          "company_id": "abc"
        },
        "value": [1743465600, "1"]
      }
    ]
  }
}

Error Responses#

Related#

• Session Data — List and filter individual sessions
• Usage — Organization-wide usage and billing data
• Tags — Session tagging