SeaChat API Wiki

• 1: SeaChat Analytics API

Authorization: Bearer [your-access-token]

curl -X 'POST' \
  'https://chat.seasalt.ai/api/v1/public/bots' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [your-access-token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspace_id": "your-workspace-id",
    "name": "My SeaChat Agent",
    "description": "An intelligent customer service agent",
    "use_case": "Customer Service",
    "live_agent_transfer": false,
    "default_response_language": "default",
    "is_enabled": true
  }'

{
    "detail": "The token: testtoken decoding failed.",
    "code": 40007,
    "parameters": {
        "token": "testtoken"
    }
}

1 - SeaChat Analytics API

Overview

The Generate Metric Report endpoint provides a unified interface for retrieving multiple conversational analytics metrics in a single request, streamlining the process of generating comprehensive reports for chatbot and conversation performance analysis. Unlike individual metric endpoints, this bulk endpoint allows you to request multiple analytics types simultaneously, reducing API calls and improving efficiency for dashboard and reporting applications. The endpoint supports all available analytics metrics including conversation overviews, activity trends, label usage, communication volumes, and detailed breakdowns, making it ideal for creating unified analytics dashboards and comprehensive chatbot performance reports.

Authentication via API key is required to ensure secure access to workspace conversation data.

Prerequisites

Ensure the following are in place:

1. Generate Your API Key

All APIs require a valid API key issued from your workspace. All requests must include a valid API key in the request header (X-API-KEY: <your_api_key>).

• Go to Workspace → API Key tab in your SeaChat dashboard.

• Generate your API key by clicking the Create API Key button and select SeaChat API Access as the scope.

• Copy the generated API key and keep it safe. This key is required in the X-API-KEY: <your_api_key> header for all requests.

Endpoint

POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report

Use this endpoint to generate multiple conversational analytics metrics in a single request, providing a comprehensive view of your chatbot and conversation performance across various dimensions.

Sample Request

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview", "activity_trend"],
    "range_type": "last_30_days",
    "timezone": "America/Los_Angeles",
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Request Fields

The request body uses the AnalyticsRequestType schema with the following fields:

Note: Fields marked with specific metric requirements are only used with certain metrics. See individual metric sections for detailed field dependencies.

Metrics Use Case

Available Metrics

The following metrics are available through this endpoint. Each metric has specific requirements and returns structured data:

Performance Tip: Requesting multiple related metrics in a single call is more efficient than separate requests. However, avoid combining resource-intensive metrics like conversation_overview_yearly with others unless necessary.

CONVERSATION_OVERVIEW

Provides comprehensive conversation statistics over a specified time range, including message counts, user interactions, and percentage changes compared to the previous period.

Use Cases:

• Dashboard overview widgets
• Comparing current vs previous period performance
• Monitoring agent workload and bot effectiveness
• Chatbot performance analysis

Required Fields:

• metrics: Must include "conversation_overview"
• range_type: Time range specification (use last_30_days, last_7_days, etc.)

Optional Fields:

• timezone (string): Timezone for date calculations and filtering

  • Default: "UTC"
  • Example: "America/Los_Angeles", "Asia/Tokyo", "Europe/London"
  • Recommendation: Set to your business timezone for accurate reporting

• exclude_empty_response (boolean): Filter out conversations with no bot or agent responses

  • Default: false (includes all conversations)
  • Example: true to focus only on engaged conversations
  • Use case: Set to true when analyzing actual engagement vs total traffic

Note: This metric automatically calculates percentage changes by comparing with the equivalent previous period.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview"],
    "range_type": "last_30_days",
    "timezone": "America/Los_Angeles",
    "exclude_empty_response": true
  }'

Sample Response:

{
  "conversation_overview": {
    "conversations": 150,
    "messages": 2500,
    "bot_messages": 1200,
    "agent_messages": 800,
    "live_agent_requests": 50,
    "distinct_user_count": 125,
    "conversations_change_percentage": 10.5,
    "messages_change_percentage": 5.0,
    "bot_messages_change_percentage": 8.0,
    "agent_messages_change_percentage": 12.0,
    "live_agent_requests_change_percentage": 15.0,
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-01-31T23:59:59Z",
    "previous_period_start": "2023-12-01T00:00:00Z",
    "previous_period_end": "2023-12-31T23:59:59Z"
  }
}

CONVERSATION_OVERVIEW_YEARLY

Provides yearly conversation statistics with monthly breakdown and average calculations.

Use Cases:

• Annual performance reports
• Year-over-year chatbot analysis
• Monthly conversation trend identification
• Resource planning based on historical conversation data

Required Fields:

• metrics: Must include "conversation_overview_yearly"
• year: Year in YYYY format (e.g., "2024")

Optional Fields:

• timezone (string): Timezone for date calculations
  • Default: "UTC"
  • Example: "America/New_York", "Europe/Berlin", "Asia/Shanghai"
  • Note: Affects how the year boundaries are calculated

Warning: This is a resource-intensive metric. Avoid combining with multiple other metrics in high-frequency requests.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview_yearly"],
    "year": "2024",
    "timezone": "UTC"
  }'

Sample Response:

{
  "conversation_overview_yearly": {
    "total_conversations": 1800,
    "total_messages": 15000,
    "average_messages_per_conversation": 8.33,
    "monthly_messages": {
      "January": 1200,
      "February": 1100,
      "March": 1300,
      "April": 1250,
      "May": 1400,
      "June": 1350,
      "July": 1450,
      "August": 1300,
      "September": 1200,
      "October": 1250,
      "November": 1100,
      "December": 1100
    }
  }
}

CONVERSATION_BREAKDOWN

Provides detailed breakdown of conversation activity by channel, day of week, and hour of day, useful for identifying peak activity periods and channel preferences.

Use Cases:

• Staffing optimization (identify peak hours/days)
• Channel performance analysis
• Customer behavior pattern analysis
• Resource allocation planning for chatbot support

Required Fields:

• metrics: Must include "conversation_breakdown"
• start_date: Start of analysis period (ISO 8601 format)
• end_date: End of analysis period (ISO 8601 format)

Optional Fields:

• timezone (string): Timezone for hour-of-day and day-of-week analysis
  • Default: "UTC"
  • Example: "America/Chicago", "Asia/Seoul", "Australia/Sydney"
  • Important: Critical for accurate hour-of-day patterns as customer activity varies by local time
  • Use case: Set to your primary customer base timezone for meaningful staffing insights

Performance Tip: Limit date ranges to 90 days or less for optimal performance.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_breakdown"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "timezone": "UTC"
  }'

Sample Response:

{
  "conversation_breakdown": {
    "channel_summary": {
      "WebChat": {
        "user_count": 45,
        "inbound_message_count": 320,
        "outbound_message_count": 280,
        "total_message_count": 600
      },
      "SMS": {
        "user_count": 30,
        "inbound_message_count": 150,
        "outbound_message_count": 120,
        "total_message_count": 270
      }
    },
    "messages_by_day": {
      "Monday": 60,
      "Tuesday": 80,
      "Wednesday": 75,
      "Thursday": 90,
      "Friday": 100,
      "Saturday": 40,
      "Sunday": 25
    },
    "messages_by_hour": {
      "0": 5,
      "1": 2,
      "2": 0,
      "3": 1,
      "4": 3,
      "5": 8,
      "6": 12,
      "7": 20,
      "8": 30,
      "9": 40,
      "10": 50,
      "11": 60,
      "12": 45,
      "13": 35,
      "14": 28,
      "15": 22,
      "16": 18,
      "17": 15,
      "18": 10,
      "19": 8,
      "20": 5,
      "21": 4,
      "22": 2,
      "23": 1
    }
  }
}

LABEL_OVERVIEW

Returns comprehensive information about all conversation labels in the workspace, including usage counts and label metadata.

Use Cases:

• Label management and cleanup
• Understanding conversation categorization patterns
• Contact segmentation analysis
• Label performance tracking for chatbot conversations

Required Fields:

• metrics: Must include "label_overview"

Optional Fields:

• None (this metric automatically returns all workspace labels including both custom and system labels)

Note: This metric includes both custom and system labels. System labels may have null workspace_id.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["label_overview"]
  }'

Sample Response:

{
  "label_overview": [
    {
      "id": "label-123",
      "name": "Support",
      "color": "#FF5733",
      "description": "Customer support inquiries",
      "total_count": 150,
      "is_system": false,
      "created_time": "2024-01-01T00:00:00Z",
      "updated_time": "2024-01-15T12:30:00Z"
    },
    {
      "id": "label-456",
      "name": "Sales",
      "color": "#33C3FF",
      "description": "Sales-related conversations",
      "total_count": 89,
      "is_system": false,
      "created_time": "2024-01-01T00:00:00Z",
      "updated_time": "2024-01-10T09:15:00Z"
    }
  ]
}

COMMUNICATION_VOLUME

Provides counts of inbound/outbound voice calls and non-voice messages for a specified time period.

Use Cases:

• Communication channel analysis
• Voice vs text usage tracking in chatbot interactions
• Capacity planning
• Service level monitoring

Required Fields:

• metrics: Must include "communication_volume"
• start_date: Start of analysis period (ISO 8601 format)
• end_date: End of analysis period (ISO 8601 format)

Optional Fields:

• timezone (string): Timezone for date range filtering
  • Default: "UTC"
  • Example: "America/Denver", "Europe/Paris", "Asia/Mumbai"
  • Use case: Ensures accurate date boundaries for your business operations

Note: “Non-voice” includes SMS, chat messages, and other text-based communications through your chatbot.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["communication_volume"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Sample Response:

{
  "communication_volume": {
    "inbound_voice_count": 25,
    "outbound_voice_count": 15,
    "inbound_non_voice_count": 450
  }
}

ACTIVITY_TREND

Tracks communication activity changes over time, with breakdowns by sender type or call direction, including percentage change calculations.

Use Cases:

• Trend analysis over time
• Bot vs human agent performance tracking
• Seasonal pattern identification in chatbot usage
• Growth/decline analysis

Required Fields:

• metrics: Must include "activity_trend"
• start_date: Start of analysis period (ISO 8601 format)
• end_date: End of analysis period (ISO 8601 format)

Optional Fields:

• message_type (string): Type of communication to analyze

  • Default: "messages"
  • Options:
    • "messages": Shows breakdown by CUSTOMER/AGENT/BOT/SYSTEM sender types
    • "calls": Shows breakdown by inbound/outbound call direction
  • Example: "messages" for chat analysis, "calls" for voice traffic analysis

• time_unit (string): Time period for data aggregation

  • Default: "month"
  • Options: "day", "month", "year"
  • Example: Use "day" for detailed short-term analysis, "month" for trend analysis
  • Performance tip: Use "month" or "year" for large date ranges

• timezone (string): Timezone for date grouping

  • Default: "UTC"
  • Example: "America/Phoenix", "Europe/Rome", "Asia/Bangkok"
  • Use case: Ensures trend periods align with your business calendar

Performance Tip: Use "month" or "year" time_unit for large date ranges to reduce response size.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["activity_trend"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "message_type": "messages",
    "time_unit": "day"
  }'

Sample Response:

{
  "activity_trend": {
    "time_unit": "day",
    "data": [
      {
        "period": "2024-01-01",
        "CUSTOMER": 45,
        "AGENT": 60,
        "BOT": 20,
        "SYSTEM": 5
      },
      {
        "period": "2024-01-02",
        "CUSTOMER": 50,
        "AGENT": 70,
        "BOT": 25,
        "SYSTEM": 3
      }
    ],
    "change_percent": 12.5
  }
}

LABEL_USAGE

Returns label usage statistics over time, grouped by the specified time unit.

Use Cases:

• Label trend analysis
• Campaign effectiveness tracking through conversation labels
• Seasonal label usage patterns
• Specific conversation category monitoring

Required Fields:

• metrics: Must include "label_usage"
• start_date: Start of analysis period (ISO 8601 format)
• end_date: End of analysis period (ISO 8601 format)

Optional Fields:

• time_unit (string): Time period for data grouping

  • Default: "month"
  • Options: "day", "month", "year"
  • Example: "day" for daily label application patterns, "month" for monthly trends
  • Use case: Choose based on your analysis timeframe and data volume

• labels (array of strings): Specific label names to include in analysis

  • Default: Returns data for all available labels in the workspace
  • Example: ["support", "sales", "billing"] to focus on key business categories
  • Performance tip: Filter to specific labels to reduce response size and focus analysis
  • Use case: Monitor specific campaign labels or department categories

• timezone (string): Timezone for time period boundaries

  • Default: "UTC"
  • Example: "America/Los_Angeles", "Europe/London", "Asia/Tokyo"
  • Use case: Align time periods with your business calendar for accurate trend analysis

Tip: Use the labels filter to focus on specific labels of interest and reduce response size.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["label_usage"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-02-29T23:59:59",
    "time_unit": "month",
    "labels": ["support", "sales", "billing"]
  }'

Sample Response:

{
  "label_usage": [
    {
      "period": "2024-01",
      "labels": [
        { "name": "support", "count": 45 },
        { "name": "sales", "count": 32 },
        { "name": "billing", "count": 18 }
      ]
    },
    {
      "period": "2024-02",
      "labels": [
        { "name": "support", "count": 52 },
        { "name": "sales", "count": 28 },
        { "name": "billing", "count": 22 }
      ]
    }
  ]
}

TOTAL_USAGE

Returns summary of total voice call duration and chat message counts over a specified period.

Use Cases:

• Billing and usage tracking for chatbot services
• Resource consumption monitoring
• Service usage summaries
• Cost analysis

Required Fields:

• metrics: Must include "total_usage"

Optional Fields:

• start_date (string, ISO 8601 datetime): Beginning of the analysis period

  • Default: If omitted, uses all available historical data from the beginning of records
  • Example: "2024-01-01T00:00:00", "2024-06-15T00:00:00-07:00"
  • Use case: Specify to analyze usage for a particular period, or omit for total lifetime usage

• end_date (string, ISO 8601 datetime): End of the analysis period

  • Default: If omitted, uses all available data up to the current time
  • Example: "2024-12-31T23:59:59", "2024-06-30T23:59:59+08:00"
  • Use case: Specify for period analysis, or omit for usage up to now

• timezone (string): Timezone for date range interpretation

  • Default: "UTC"
  • Example: "America/New_York", "Europe/Amsterdam", "Asia/Singapore"
  • Use case: Ensures date boundaries match your business timezone

Note: If no date range is specified, returns total usage across all available data.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["total_usage"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Sample Response:

{
  "total_usage": {
    "total_voice_minutes": 450.5,
    "total_chat_responses": 2500
  }
}

LABEL_RELATION

Analyzes the relationship and overlap between two specific conversation labels, showing how frequently they appear together and their individual usage patterns.

Use Cases:

• Understanding label co-occurrence patterns
• Identifying related conversation topics
• Optimizing label taxonomy and organization
• Cross-category analysis (e.g., how often “support” conversations are also “billing”)
• Label performance comparison

Required Fields:

• metrics: Must include "label_relation"
• labels: Must contain exactly 2 label names - the first is the base label, the second is the comparison label
• start_date: Start of analysis period (ISO 8601 format)
• end_date: End of analysis period (ISO 8601 format)

Optional Fields:

• gptbot_id (string): Filter results for a specific chatbot

  • Default: Analyzes all conversations in the workspace
  • Example: "bot_12345" to focus on one specific bot’s conversations
  • Use case: Compare label relationships across different chatbots

• timezone (string): Timezone for date range filtering

  • Default: "UTC"
  • Example: "America/Los_Angeles", "Europe/Berlin", "Asia/Tokyo"
  • Use case: Ensures accurate date boundaries for your analysis period

Note: The order of labels matters - the first label in the array is treated as the “base label” and the second as the “comparison label”. This affects how overlap percentages are calculated.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["label_relation"],
    "labels": ["customer service", "solved"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "gptbot_id": "bot_12345"
  }'

Sample Response:

{
  "label_relation": {
    "base_label": "customer service",
    "base_count": 10,
    "comparison_label": "solved",
    "both_labels_count": 4,
    "ratio": 0.4,
    "date_range": {
      "start_date": "2024-01-01T00:00:00",
      "end_date": "2024-01-31T23:59:59"
    }
  }
}

Response Fields Explanation:

• base_label: Name of the first label specified in the request (the base label for comparison)
• base_count: Total number of conversations that have the base label
• comparison_label: Name of the second label specified in the request
• both_labels_count: Number of conversations that have both labels applied
• ratio: Overlap ratio calculated as both_labels_count / base_count (0.4 = 4 out of 10 base label conversations also have the comparison label)
• date_range: The actual date range used for the analysis
  • start_date: Beginning of the analysis period
  • end_date: End of the analysis period

CSAT (Customer Satisfaction)

Retrieves Customer Satisfaction survey results and ratings for conversations handled by a specific chatbot.

Use Cases:

• Monitor chatbot customer satisfaction performance
• Track satisfaction trends over time
• Identify periods of high/low customer satisfaction
• Compare satisfaction across different time periods
• Generate satisfaction reports for stakeholders

Required Fields:

• metrics: Must include "csat"
• gptbot_id: The specific chatbot ID to analyze satisfaction data for

Optional Fields:

• start_date (string, ISO 8601 datetime): Beginning of the analysis period

  • Default: If omitted, uses all available historical satisfaction data
  • Example: "2024-01-01T00:00:00", "2024-06-15T00:00:00-07:00"
  • Use case: Specify to analyze satisfaction for a particular period

• end_date (string, ISO 8601 datetime): End of the analysis period

  • Default: If omitted, uses all available data up to the current time
  • Example: "2024-12-31T23:59:59", "2024-06-30T23:59:59+08:00"
  • Use case: Set end boundary for period analysis

• timezone (string): Timezone for date range interpretation

  • Default: "UTC"
  • Example: "America/New_York", "Europe/Amsterdam", "Asia/Singapore"
  • Use case: Ensures date boundaries match your business timezone

Important: This metric requires gptbot_id because CSAT surveys are associated with specific chatbot interactions. You cannot retrieve CSAT data without specifying which bot’s satisfaction ratings to analyze.

Sample Request:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["csat"],
    "gptbot_id": "bot_12345",
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "timezone": "America/Los_Angeles"
  }'

Sample Response:

{
  "csat": {
    "total_responses": 2,
    "average_rating": 3.5,
    "satisfaction_rate": 50.0,
    "rating_counts": {
      "1": 0,
      "2": 0,
      "3": 1,
      "4": 1,
      "5": 0
    },
    "responses": [
      {
        "id": 9,
        "conversation_id": "conv-12345",
        "form_id": "8c7458f6a27a4554bf1a3e37b7790045",
        "rating": 3,
        "created_at": "2025-05-30T01:35:11.769173",
        "data": {
          "rating": 3.0,
          "comment": "Good bot but can be better"
        },
        "conversation_title": "+1206123456789",
        "conversation_link": "https://chat-staging.seasalt.ai/gpt/workspace/ws-123/bot/bot-123/conversations/conv-123"
      },
      {
        "id": 8,
        "conversation_id": "conv-98765",
        "form_id": "8c7458f6a27a4554bf1a3e37b7790045",
        "rating": 4,
        "created_at": "2025-06-12T00:29:07.893663",
        "data": {
          "rating": 4.0,
          "comment": "Fast response, and accurate information. Nice!"
        },
        "conversation_title": "+1408123456789",
        "conversation_link": "https://chat-staging.seasalt.ai/gpt/workspace/ws-123/bot/bot-123/conversations/conv-98765"
      }
    ]
  }
}

Response Fields Explanation:

• total_responses: Total number of CSAT survey responses received
• average_rating: Mean satisfaction rating (typically on 1-5 scale)
• satisfaction_rate: Percentage of responses rated 4 or 5 (satisfied customers)
• rating_counts: Breakdown of responses by rating value (1-5)
• responses: Array of individual CSAT response records containing:
  • id: Unique response identifier
  • conversation_id: ID of the conversation this rating relates to
  • form_id: ID of the CSAT form used
  • rating: Numerical rating given by the customer
  • created_at: Timestamp when the rating was submitted
  • data: Detailed response data including rating, comment, and form metadata
  • conversation_title: Display title of the conversation
  • conversation_link: Direct link to view the conversation in SeaChat dashboard

Complete Sample Request and Response

Sample Request with Multiple Metrics:

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      "conversation_overview",
      "communication_volume",
      "label_overview"
    ],
    "range_type": "last_30_days",
    "timezone": "America/Los_Angeles",
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  }'

Sample Successful Response:

{
  "conversation_overview": {
    "conversations": 150,
    "messages": 2500,
    "bot_messages": 1200,
    "agent_messages": 800,
    "live_agent_requests": 50,
    "distinct_user_count": 125,
    "conversations_change_percentage": 10.5,
    "messages_change_percentage": 5.0,
    "bot_messages_change_percentage": 8.0,
    "agent_messages_change_percentage": 12.0,
    "live_agent_requests_change_percentage": 15.0,
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-01-31T23:59:59Z",
    "previous_period_start": "2023-12-01T00:00:00Z",
    "previous_period_end": "2023-12-31T23:59:59Z"
  },
  "communication_volume": {
    "inbound_voice_count": 25,
    "outbound_voice_count": 15,
    "inbound_non_voice_count": 450
  },
  "label_overview": [
    {
      "id": "label-123",
      "name": "Support",
      "color": "#FF5733",
      "description": "Customer support inquiries",
      "total_count": 150,
      "is_system": false,
      "created_time": "2024-01-01T00:00:00Z",
      "updated_time": "2024-01-15T12:30:00Z"
    },
    {
      "id": "label-456",
      "name": "Sales",
      "color": "#33C3FF",
      "description": "Sales-related conversations",
      "total_count": 89,
      "is_system": false,
      "created_time": "2024-01-01T00:00:00Z",
      "updated_time": "2024-01-10T09:15:00Z"
    }
  ]
}

Error Responses

The API returns specific error messages to help you troubleshoot issues:

400 Bad Request - Missing Required Field:

{
  "detail": "Range type is required for conversation overview"
}

Solution: Add the range_type field when using the conversation_overview metric.

400 Bad Request - Invalid Metric:

{
  "detail": "Unsupported metric: invalid_metric_name"
}

Solution: Check the metric name against the supported list in the schema table above.

400 Bad Request - Date Range Required:

{
  "detail": "Start date and end date are required for conversation breakdown"
}

Solution: Provide both start_date and end_date fields for date-range metrics.

401 Unauthorized:

{
  "detail": "Invalid API key"
}

Solution: Verify your API key is correct and properly formatted in the X-API-KEY header.

422 Validation Error:

{
  "detail": [
    {
      "loc": ["body", "metrics"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Solution: Ensure all required fields are included in your request body.

Common Error Scenarios

Best Practices

Request Optimization

1. Batch Related Metrics: Request related metrics together to minimize API calls and ensure data consistency.

   • ✅ Good: ["conversation_overview", "communication_volume"]
   • ❌ Avoid: Separate calls for each metric

2. Timezone Consistency: Always specify the same timezone across related requests to ensure accurate comparisons.

   • ✅ Good: Set "timezone": "America/Los_Angeles" for all requests
   • ❌ Avoid: Mixing UTC and local timezones in related queries

3. Date Range Optimization:

   • Use range_type for standard periods instead of custom dates when possible
   • Limit date ranges to 90 days or less for complex metrics
   • Ensure start_date is before end_date

Error Handling

4. Comprehensive Error Handling: Implement proper error handling for each metric, as some may succeed while others fail due to missing required fields.

   // Example error handling
   try {
     const response = await fetch('/api/v1/analytics/generate_metric_report', {
       method: 'POST',
       headers: { 'X-API-KEY': `${apiKey}`, 'Content-Type': 'application/json' },
       body: JSON.stringify(requestBody),
     });
     if (!response.ok) {
       const error = await response.json();
       console.error('API Error:', error.detail);
     }
   } catch (error) {
     console.error('Network Error:', error);
   }
   

Performance Optimization

5. Query Performance:

   • Avoid conversation_overview_yearly in high-frequency requests
   • Use appropriate time_unit values (prefer month over day for large ranges)
   • Consider implementing client-side caching for frequently requested combinations
   • Set reasonable request timeouts (30-60 seconds for complex queries)

6. Resource Management:

   • Don’t request more metrics than needed for your use case
   • Use label filtering (labels parameter) to reduce response size
   • Monitor API quota usage for high-volume applications

Data Consistency

7. Timezone Handling:

   • Always specify timezone for business reporting
   • Use the same timezone across related dashboard widgets
   • Consider user’s local timezone for UI display

8. Date Range Logic:

   • Validate date ranges on the client side before API calls
   • Handle edge cases like month boundaries and leap years
   • Consider business calendar vs calendar dates for reporting

Real-World Usage Examples

Chatbot Dashboard Overview (Most Common)

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["conversation_overview", "communication_volume"],
    "range_type": "last_30_days",
    "timezone": "America/New_York"
  }'

Detailed Conversation Analysis

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["activity_trend", "conversation_breakdown"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "time_unit": "day",
    "timezone": "UTC"
  }'

Label Performance Review

curl -X POST https://chat.seasalt.ai/api/v1/analytics/generate_metric_report \
  -H "X-API-KEY your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["label_overview", "label_usage"],
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59",
    "labels": ["support", "sales", "billing"]
  }'