Insights

The Insights API allows you to retrieve AI-generated insights from your recordings. Insights are automatically extracted from processed recordings and provide actionable information about user feedback, pain points, and key topics.

Overview

Insights are automatically generated when recordings are processed. Each insight includes:

Title and description - Summary of the finding
Priority level - Importance (low, medium, high, critical)
Status - Current state (active, completed, dismissed)
Tags - Categorization for filtering
Source - How the insight was created (automatic, chat, manual)

List Project Insights

Retrieves a paginated list of insights for a project. You can filter by recording and control pagination.


GET /v2/projects/{projectId}/insights

Headers

Header	Type	Required	Description
`x-api-key`	string	Yes	Your API key (requires `read` permission)

Path Parameters

Parameter	Type	Description
`projectId`	string	The project’s unique identifier

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number (1-indexed)
`limit`	number	20	Items per page (max 100)
`recordingId`	string	-	Filter insights by recording ID (optional)

Response

200 OK


{
  "data": [
    {
      "id": "507f1f77bcf86cd799439014",
      "projectId": "507f1f77bcf86cd799439011",
      "title": "Users struggle with payment method selection",
      "description": "Multiple participants mentioned confusion about which payment options were available. The payment method selector was not intuitive and lacked clear visual indicators.",
      "source": "automatic",
      "status": "active",
      "priority": "high",
      "tags": ["payment", "UX", "checkout"],
      "recordingId": "507f1f77bcf86cd799439013",
      "createdAt": "2024-12-26T10:45:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439015",
      "projectId": "507f1f77bcf86cd799439011",
      "title": "Checkout error messages need improvement",
      "description": "Users found error messages during checkout to be unclear and unhelpful.",
      "source": "automatic",
      "status": "active",
      "priority": "medium",
      "tags": ["checkout", "errors", "UX"],
      "recordingId": "507f1f77bcf86cd799439013",
      "createdAt": "2024-12-26T10:46:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "totalPages": 3
}

Response Fields

Field	Type	Description
`data`	array	Array of insight objects
`data[].id`	string	Unique insight identifier
`data[].projectId`	string	Project ID this insight belongs to
`data[].title`	string	Insight title/summary
`data[].description`	string \| null	Detailed description of the insight
`data[].source`	string	How the insight was created (see sources below)
`data[].status`	string	Current status (see statuses below)
`data[].priority`	string	Priority level (see priorities below)
`data[].tags`	string[]	Array of tags for categorization
`data[].recordingId`	string \| null	Related recording ID (if applicable)
`data[].createdAt`	string	ISO 8601 timestamp when insight was created
`total`	number	Total number of insights matching the query
`page`	number	Current page number
`limit`	number	Items per page
`totalPages`	number	Total number of pages

Insight Sources

Source	Description
`automatic`	AI-generated from recording analysis (most common)
`chat`	Created from AI chat conversation with the recording context
`manual`	Manually created by a user in the dashboard

Insight Statuses

Status	Description
`active`	Insight is active and being tracked
`completed`	Insight has been addressed/resolved
`dismissed`	Insight has been dismissed (not relevant)

Insight Priorities

Priority	Description
`low`	Minor issue or nice-to-have improvement
`medium`	Moderate impact on user experience (default)
`high`	Significant user pain point requiring attention
`critical`	Blocking issue, urgent priority

Example Requests

Get first page of insights:


curl -X GET "https://api.yeino.com/v2/projects/507f1f77bcf86cd799439011/insights" \
  -H "x-api-key: yno_live_abc123..."

Get insights for a specific recording:


curl -X GET "https://api.yeino.com/v2/projects/507f1f77bcf86cd799439011/insights?recordingId=507f1f77bcf86cd799439013" \
  -H "x-api-key: yno_live_abc123..."

Paginate through results (page 2, 50 items per page):


curl -X GET "https://api.yeino.com/v2/projects/507f1f77bcf86cd799439011/insights?page=2&limit=50" \
  -H "x-api-key: yno_live_abc123..."

Get all insights (maximum limit):


curl -X GET "https://api.yeino.com/v2/projects/507f1f77bcf86cd799439011/insights?limit=100" \
  -H "x-api-key: yno_live_abc123..."

Error Responses

Status Code	Error	Description
400	`Bad Request`	Invalid query parameters (e.g., limit > 100, page < 1)
401	`Unauthorized`	Invalid or missing API key
403	`Forbidden`	API key doesn’t have `read` permission
404	`Not Found`	Project not found or not accessible to your organization
500	`Internal Server Error`	Server error (contact support if persistent)

400 Bad Request Example:


{
  "statusCode": 400,
  "message": "Limit cannot exceed 100.",
  "error": "Bad Request"
}

404 Not Found Example:


{
  "statusCode": 404,
  "message": "Project not found.",
  "error": "Not Found"
}

Use Cases

Insight Dashboards - Display all insights for a project with filtering and pagination
Recording Analysis - Get insights specific to a recording after processing
Reporting - Aggregate insights across projects for analysis
Integration - Sync insights to external tools (Jira, Linear, etc.)
Monitoring - Track high-priority insights that need attention

Pagination Best Practices

Start with default pagination - Use page=1 and limit=20 for initial requests
Increase limit for bulk operations - Use limit=100 when fetching all insights
Handle empty results - Check if total === 0 or data.length === 0
Respect rate limits - Don’t make rapid pagination requests (use reasonable delays)
Cache results - Consider caching insights since they don’t change frequently

Example: Fetching All Insights


async function fetchAllInsights(projectId, apiKey) {
  const allInsights = [];
  let page = 1;
  let hasMore = true;
 
  while (hasMore) {
    const response = await fetch(
      `https://api.yeino.com/v2/projects/${projectId}/insights?page=${page}&limit=100`,
      {
        headers: { 'x-api-key': apiKey },
      }
    );
    const data = await response.json();
 
    allInsights.push(...data.data);
    hasMore = page < data.totalPages;
    page++;
  }
 
  return allInsights;
}

Notes

Insights are only available after recordings have been processed (status: "completed").
The recordingId filter is optional. Omit it to get insights from all recordings in the project.
Insights are ordered by creation date (newest first).
Tags are automatically generated but can be manually adjusted in the dashboard.