Insights API

Retrieve performance insights for agents and conversations.

Agent Insights

Get aggregated performance insights for an agent based on logged conversations.

GET /api/v1/agents/:id/insights

Query Parameters

Parameter	Type	Default	Description
days	number	30	Number of days to look back (7, 30, 90)

Response

{
  "agentId": "agent_abc123",
  "period": "30d",
  "metrics": {
    "taskCompletion": 87,
    "averageSentiment": "positive",
    "conversationCount": 1247,
    "averageTurns": 4.2,
    "completionRate": 0.92,
    "abandonmentRate": 0.08
  },
  "topics": [
    { "name": "order status", "count": 423 },
    { "name": "refunds", "count": 312 },
    { "name": "shipping", "count": 287 }
  ],
  "issues": [
    {
      "description": "Users often confused about return policy",
      "frequency": 0.15,
      "severity": "medium"
    }
  ],
  "recommendations": [
    "Add clear return policy instructions",
    "Include order tracking link in responses"
  ],
  "sentiment": {
    "positive": 0.72,
    "neutral": 0.20,
    "negative": 0.08
  },
  "generatedAt": "2025-01-20T15:00:00Z"
}

Example

# Get insights for last 30 days (default)
curl https://converra.ai/api/v1/agents/agent_abc123/insights \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get insights for last 7 days
curl "https://converra.ai/api/v1/agents/agent_abc123/insights?days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK Usage

const insights = await converra.agents.getInsights('agent_abc123', {
  days: 30
});

console.log('Task completion:', insights.metrics.taskCompletion);
console.log('Top topics:', insights.topics);
console.log('Issues found:', insights.issues);

---

Conversation Insights

Get detailed insights for a specific conversation.

GET /api/v1/conversations/:id/insights

Generation status and retained results

When a publication exists, GET responses (including MCP get_conversation_insights) include the nullable generationStatus overlay:

{
  "generationStatus": {
    "state": "retrying",
    "lastAttemptAt": "2026-09-09T16:43:06.000Z",
    "nextRetryAt": "2026-09-09T16:44:06.000Z",
    "retryCount": 1,
    "message": "The latest insight refresh failed. An automatic retry is scheduled."
  }
}

This example shows only the overlay. The full response retains the last valid insights and their original timestamps. States are running, retrying, failed, and ineligible. failed means no automatic retry is scheduled; ineligible identifies conversations below the substantive-message minimum. The status is null when lifecycle is unknown or available, or when a newer publication supersedes the observed attempt. Null does not establish evidence quality or freshness of source inputs. Raw internal errors are not included.

The SDK exports InsightGenerationStatus through optional, nullable ConversationInsights.generationStatus. Optionality supports older servers and write responses. When no publication exists, the existing lifecycle envelope instead has top-level status, reason, retryCount, and nextRetryAt (some fields may be absent). Narrow on top-level status before reading insight fields. The overlay is not part of immutable publication hashes.

Response

{
  "conversationId": "conv_xyz789",
  "sentiment": "positive",
  "sentimentScore": 0.82,
  "taskCompleted": true,
  "topics": ["order status", "shipping", "tracking"],
  "summary": "Customer inquired about order #12345 status. Agent provided accurate shipping information and tracking link. Customer expressed satisfaction with the response.",
  "keyMoments": [
    {
      "turn": 2,
      "type": "question",
      "description": "Customer asked about shipping status"
    },
    {
      "turn": 3,
      "type": "resolution",
      "description": "Agent provided tracking information"
    }
  ],
  "issues": [],
  "qualityScore": 88,
  "createdAt": "2025-01-20T14:35:00Z"
}

Example

curl https://converra.ai/api/v1/conversations/conv_xyz789/insights \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK Usage

const insights = await converra.conversations.getInsights('conv_xyz789');

console.log('Sentiment:', insights.sentiment);
console.log('Task completed:', insights.taskCompleted);
console.log('Summary:', insights.summary);

---

Insights Fields

Metrics

Field	Type	Description
taskCompletion	number	Percentage of conversations where user's goal was achieved (0-100)
averageSentiment	string	Overall sentiment trend (positive, neutral, negative, mixed)
conversationCount	number	Total conversations in period
averageTurns	number	Average messages per conversation
completionRate	number	Ratio of completed conversations (0-1)
abandonmentRate	number	Ratio of abandoned conversations (0-1)

Topics

Topics are automatically extracted from conversations:

interface Topic {
  name: string;      // Topic name
  count: number;     // Number of conversations mentioning this topic
}

Issues

Identified patterns that may indicate problems:

interface Issue {
  description: string;    // What the issue is
  frequency: number;      // How often it occurs (0-1)
  severity: 'low' | 'medium' | 'high';
}

Sentiment Distribution

interface SentimentDistribution {
  positive: number;  // Ratio of positive conversations (0-1)
  neutral: number;   // Ratio of neutral conversations (0-1)
  negative: number;  // Ratio of negative conversations (0-1)
}

---

Insights via MCP

How is my support agent performing?

Response:

Insights for Customer Support (last 30 days):
- Task completion: 87%
- Avg sentiment: Positive
- Common topics: order status, refunds, shipping
- Improvement opportunity: Users often confused about return policy

---

Error Responses

Agent Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found"
  }
}

Status: 404 Not Found

Insufficient Data

{
  "error": {
    "code": "INSUFFICIENT_DATA",
    "message": "Not enough conversations to generate insights. Log at least 10 conversations."
  }
}

Status: 422 Unprocessable Entity

---

Best Practices

Check Insights Regularly

Review insights weekly to catch issues early:

// Weekly insights check
const insights = await converra.agents.getInsights('agent_123', { days: 7 });

if (insights.metrics.taskCompletion < 80) {
  console.warn('Task completion dropped below 80%');
}

if (insights.issues.length > 0) {
  console.warn('New issues detected:', insights.issues);
}

Use Insights to Guide Optimization

Target specific issues with optimization intent:

const insights = await converra.agents.getInsights('agent_123');

if (insights.issues.some(i => i.description.includes('return policy'))) {
  await converra.optimizations.trigger({
    agentId: 'agent_123',
    intent: {
      targetImprovements: ['clarity'],
      hypothesis: 'Adding return policy details will reduce confusion'
    }
  });
}