Insights API

Retrieve performance insights for prompts and conversations.

Prompt Insights

Get aggregated performance insights for a prompt based on logged conversations.

GET /api/v1/prompts/:id/insights

Query Parameters

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

Response

{
  "promptId": "prompt_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/prompts/prompt_abc123/insights \
  -H "Authorization: Bearer YOUR_API_KEY"

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

SDK Usage

const insights = await converra.prompts.getInsights('prompt_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

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

Prompt Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Prompt 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.prompts.getInsights('prompt_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.prompts.getInsights('prompt_123');

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