Analytics API

Analytics API - BETA

Overview

The Analytics API provides access to conversations, metrics, and related resources for conversational AI systems. This RESTful API allows you to retrieve conversation data, calculate performance metrics, and access configuration information for agents, profiles, and tools.

The specification file can be found here: file analytics_api.yaml

Authentication

All API requests require authentication using a product token in the header. This product token will be provided securely.

X-CM-PRODUCTTOKEN: your-product-token

General Request Structure

Base URL

https://api.cm.com/halo/analytics/api/v1/

Common Parameters

• _{{{account_id}}: Required path parameter (UUID) identifying the account}

• _{{{profile_id}}: Optional query parameter to filter results by specific profile}

• _{{{start_date}} / {{end_date}}: ISO 8601 datetime strings for filtering time-based data (UTC timezone expected, e.g., 2025-01-01T00:00:00Z)}

Pagination

Results are paginated using cursor-based pagination:

• _{{{limit}}: Number of items to return (max 1,000, default 1,000)}

• _{{{cursor}}: Token for retrieving next/previous pages}

General Response Structure

All responses follow a consistent envelope structure:

{
"data": [...],
"meta": {
"total_count": 1234
},
"pagination": {
"page_size": 10,
"has_next": true,
"has_previous": false,
"next_cursor": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"previous_cursor": null
}
}

Response Fields

• _{{{data}}: Array of requested resources}

• _{{{meta}}: Metadata including total count of available items}

• _{{{pagination}}: Information for navigating through paginated results}

Error Responses

The API returns standard HTTP status codes with descriptive error messages:

• _{{{400}}: Bad request - Invalid parameters}

• _{{{404}}: Resource not found}

• _{{{422}}: Validation error - Invalid request format}

• _{{{500}}: Internal server error}

API Endpoints

Conversations

GET /api/v1/accounts/{account_id}/conversations

Retrieve conversations for an account with filtering options.

Parameters:

• _{{{account_id}} (path, required): Account UUID}

• _{{{start_date}} (query, required): Start date for filtering (ISO 8601 format, UTC timezone expected, e.g., 2025-01-01T00:00:00Z)}

• _{{{end_date}} (query, required): End date for filtering (ISO 8601 format, UTC timezone expected, e.g., 2025-01-31T23:59:59Z)}

• _{{{profile_id}} (query, optional): Filter by specific profile ID}

• _{{{limit}} (query, optional): Number of results (1-1,000 default 1,000)}

• _{{{cursor}} (query, optional): Pagination curso}r

Response:

List of conversation data with basic information including conversation IDs, recognition rates, agent interactions, and metadata.

GET /api/v1/accounts/{account_id}/conversations/{conversation_id}

Retrieve detailed information for a specific conversation.

Parameters:

• _{{{account_id}} (path, required): Account UUID}

• _{{{conversation_id}} (path, required): Conversation UUID}

• _{{{view}} (query, optional): View type - {{standard}} (default) or {{detailed}}}

• _{{{profile_id}} (query, optional): Profile ID for filtering}

Response:

• Standard view: Basic conversation information

• Detailed view: Complete conversation data including all interaction items and metadata

Resources

GET /api/v1/accounts/{account_id}/profiles

Retrieve available profiles for an account.

Parameters:

• _{{{account_id}} (path, required): Account UUID}

• _{{{profile_id}} (query, optional): Specific profile ID to retrieve}

Response:

List of profile objects with ID and name.

GET /api/v1/accounts/{account_id}/agents

Retrieve available agents for an account.

Parameters:

• _{{{account_id}} (path, required): Account UUID}

• _{{{profile_id}} (query, optional): Filter by profile ID}

Response:

List of agent objects with ID and name.

GET /api/v1/accounts/{account_id}/tools

Retrieve available tools for an account.

Parameters:

• _{{{account_id}} (path, required): Account UUID}

• _{{{profile_id}} (query, optional): Filter by profile ID}

Response:

List of tool objects with ID, name, and description.

Metrics

GET /api/v1/accounts/{account_id}/metrics

Calculate and retrieve performance metrics for conversations.

Parameters:

• _{{{account_id}} (path, required): Account UUID}

• _{{{start_date}} (query, required): Start date for metrics calculation (ISO 8601 format, UTC timezone expected, e.g., 2025-01-01T00:00:00Z)}

• _{{{end_date}} (query, required): End date for metrics calculation (ISO 8601 format, UTC timezone expected, e.g., 2025-01-31T23:59:59Z)}

• _{{{profile_id}} (query, optional): Filter metrics by profile ID}

Response:

Calculated metrics including:

• Total conversation count

• Average conversation duration (seconds)

• Average interactions per conversation

• Average recognition rate

• Product-specific metrics breakdown

Example Usage

Retrieve Recent Conversations

curl -X GET "/api/v1/accounts/12345678-1234-5678-1234-567812345678/conversations?start_date=2025-01-01T00:00:00Z&end_date=2025-01-08T23:59:59Z&limit=100"
-H "X-CM-PRODUCTTOKEN: your-token"

Get Conversation

curl -X GET "/api/v1/accounts/12345678-1234-5678-1234-567812345678/conversations/87654321-4321-8765-4321-876543218765"
-H "X-CM-PRODUCTTOKEN: your-token"

Get Detailed Conversation

curl -X GET "/api/v1/accounts/12345678-1234-5678-1234-567812345678/conversations/87654321-4321-8765-4321-876543218765?view=detailed"
-H "X-CM-PRODUCTTOKEN: your-token"

Get Metrics

curl -X GET "/api/v1/accounts/12345678-1234-5678-1234-567812345678/metrics?start_date=2025-01-01T00:00:00Z&end_date=2025-01-07T23:59:59Z"
-H "X-CM-PRODUCTTOKEN: your-token"

Data Models

Conversation Data

• Conversation metadata (ID, timestamps, language, channel, product)

• Recognition rates and match statistics

• Agent and tool interaction history

• Individual conversation items with roles and content

Metrics Data

• Aggregate conversation statistics

• Performance indicators (duration, interactions, recognition)

• Product-specific breakdowns

Resource Data

• Profiles: Configuration profiles for conversation processing

• Agents: Defined AI agents

• Tools: Available tools and their descriptions