Monitoring & Logs - Mindhunters API Documentation

Overview

Mindhunters provides comprehensive logging and monitoring tools to help you track API usage, debug issues, and ensure your integrations are working correctly. All logs are accessible through your workspace dashboard and provide detailed information about every request and webhook delivery.

Accessing Logs

Navigate to your Mindhunters workspace at https://your-tenant.mindhunters.ai and sign in.

Open the Logs panel

Click on “Logs” in the right section of your dashboard navigation.

Choose log type

Select the type of logs you want to view:

API Logs: Request and response details for all API calls
Webhook Logs: Webhook delivery attempts and responses

API Logs

API Logs provide detailed information about every API request made to your Mindhunters workspace.

What’s Included

Each API log entry contains:

datetime

Exact date and time when the request was received

string

HTTP method used (GET, POST, PATCH, DELETE)

string

The API endpoint that was called (e.g., /api/v1/call)

number

HTTP response status code (200, 400, 401, 422, 500, etc.)

number

How long the request took to process (in milliseconds)

string

Source IP address of the request

object

Headers included in the request (API tokens are masked for security)

object

The payload sent with the request

object

The response returned by the API

string

Client application or library information

Viewing API Log Details

Navigate to API Logs

From the Logs panel, select “API Logs”.

Browse request history

View a chronological list of all API requests. The most recent requests appear at the top.

Filter logs

Use filters to narrow down results:

Date range: Select specific time periods
Status code: Filter by success (2xx), client errors (4xx), or server errors (5xx)
Endpoint: View logs for specific API endpoints
Method: Filter by HTTP method (GET, POST, etc.)

View request details

Click on any log entry to see complete request and response details.

Example API Log Entry

{
  "id": "log_abc123xyz789",
  "timestamp": "2025-01-15T10:30:45.123Z",
  "method": "POST",
  "endpoint": "/api/v1/call",
  "statusCode": 200,
  "responseTime": 245,
  "ipAddress": "203.0.113.42",
  "userAgent": "axios/1.6.0",
  "request": {
    "headers": {
      "Authorization": "Bearer ****...****",
      "Content-Type": "application/json"
    },
    "body": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "participant": {
        "number": "+1234567890"
      }
    }
  },
  "response": {
    "success": true,
    "message": "Call initiated successfully",
    "data": {
      "id": "call_xyz789abc123",
      "status": "initiated"
    }
  }
}

Webhook Logs

Webhook Logs show all webhook delivery attempts, including successes, failures, and retries.

What’s Included

Each webhook log entry contains:

datetime

When the webhook was sent

string

The type of event (e.g., conversation.end, intent.triggered)

string

Your endpoint URL that received the webhook

number

HTTP status code returned by your endpoint

number

How long your endpoint took to respond (in milliseconds)

number

Which delivery attempt this was (1-5)

object

The complete webhook payload that was sent

object

The response returned by your endpoint

string

Any error message if the delivery failed

Viewing Webhook Log Details

Navigate to Webhook Logs

From the Logs panel, select “Webhook Logs”.

Browse delivery history

View all webhook delivery attempts in chronological order.

Filter webhooks

Filter by:

Date range: Specific time periods
Event type: Specific webhook events
Status: Success, failed, or pending retry
Status code: HTTP response codes

View delivery details

Click any log entry to see the full payload, response, and any error details.

Example Webhook Log Entry

{
  "id": "webhook_log_123abc",
  "timestamp": "2025-01-15T10:35:00.456Z",
  "eventType": "conversation.end",
  "webhookUrl": "https://api.yourcompany.com/webhooks/mihu",
  "statusCode": 200,
  "responseTime": 342,
  "attemptNumber": 1,
  "payload": {
    "event": "conversation.end",
    "timestamp": "2025-01-15T10:35:00Z",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "duration": 285
    }
  },
  "response": {
    "received": true,
    "event": "conversation.end"
  },
  "success": true
}

Monitoring Best Practices

Set up alerts for errors

Regularly check for 4xx and 5xx errors in API logs. Consider setting up external monitoring to alert you when error rates increase.

Monitor response times

Watch for slow API responses. If response times consistently exceed 2-3 seconds, investigate potential issues with your requests or network.

Track webhook delivery success

Ensure webhooks are being delivered successfully. Failed webhook deliveries may indicate issues with your endpoint.

Review failed webhook retries

If webhooks are failing repeatedly, check your endpoint’s error logs and ensure it’s responding with 200 status codes.

Monitor API usage patterns

Track your API usage to understand patterns and plan for capacity. Watch for unusual spikes that might indicate issues.

Keep logs for compliance

Download and archive logs if you need to maintain records for compliance or audit purposes.

Understanding Log Retention

Log Retention Period

API Logs: Retained for 30 days
Webhook Logs: Retained for 30 days

Logs older than the retention period are automatically deleted. Download important logs if you need to keep them longer.

Common Monitoring Scenarios

Debugging Failed API Calls

Identify the failed request

Filter API logs by status code 4xx or 5xx to find failed requests.

Review request details

Open the log entry and examine:

Request body for malformed data
Headers for missing or incorrect authentication
Response body for error messages

Check error messages

The response body will contain specific error information to help you fix the issue.

Verify and retry

Correct the issue in your code and retry the request. Check logs to confirm success.

Troubleshooting Webhook Deliveries

Check webhook logs

Open Webhook Logs and filter by failed deliveries.

Examine failure details

Look at:

Status code from your endpoint
Response time (timeouts are >5 seconds)
Error messages
Retry attempts

Test your endpoint

Verify your webhook endpoint is:

Publicly accessible
Using HTTPS
Responding within 5 seconds
Returning 200 status code

Trigger test webhook

Use the “Send Test Event” feature in Developer settings to test your endpoint.

Monitoring API Performance

Regular monitoring helps you identify performance issues early:

Track average response times: Response times should typically be under 500ms
Watch for timeout errors: Requests timing out may indicate network or server issues
Monitor error rates: Sudden spikes in errors may indicate a problem
Check rate limits: Ensure you’re not approaching rate limits

Exporting Logs

You can export logs for external analysis or compliance:

Filter logs

Use filters to select the logs you want to export.

Select export format

Choose your preferred format:

JSON: For programmatic analysis
CSV: For spreadsheet analysis

Download

Click “Export” and save the file to your device.

API Metrics Dashboard

The Mindhunters dashboard provides visual metrics for your API usage:

Available Metrics

Request Volume

Total API requests over time, broken down by endpoint

Success Rate

Percentage of successful requests (2xx status codes)

Average Response Time

Mean response time for API requests

Error Rate

Percentage of failed requests (4xx and 5xx)

Webhook Delivery Rate

Success rate for webhook deliveries

Top Endpoints

Most frequently called API endpoints

Rate Limits and Quotas

Monitor your usage against rate limits:

Standard Rate Limits

API Requests: 1000 requests per minute per workspace
Concurrent Calls: 50 simultaneous active calls
Webhook Deliveries: 100 events per second

Contact support if you need higher limits for your use case.

Checking Your Usage

View your current usage in the dashboard:

Navigate to Developer → Usage
View real-time metrics for:
- Requests per minute
- Active calls
- Webhook queue size

If you exceed rate limits, you’ll receive 429 Too Many Requests responses. Implement exponential backoff in your code to handle rate limit errors gracefully.

Advanced Monitoring

For production applications, consider implementing:

External Monitoring

Use services like Datadog, New Relic, or Prometheus to monitor API performance
Set up alerts for error rate thresholds
Track custom metrics specific to your use case

Log Aggregation

Stream logs to your own logging infrastructure
Integrate with tools like Elasticsearch, Splunk, or CloudWatch
Correlate Mindhunters logs with your application logs

Health Checks

Create scheduled health checks to verify API availability:

Example Health Check

const checkMindhuntersAPI = async () => {
  try {
    const response = await fetch(
      `https://your-tenant.mindhunters.ai/api/v1/calls?page=1&limit=1`,
      {
        headers: {
          'Authorization': `Bearer ${API_TOKEN}`
        }
      }
    );

    if (response.ok) {
      console.log('✓ Mindhunters API is healthy');
      return true;
    } else {
      console.error('✗ Mindhunters API returned error:', response.status);
      return false;
    }
  } catch (error) {
    console.error('✗ Mindhunters API is unreachable:', error.message);
    return false;
  }
};

// Run every 5 minutes
setInterval(checkMindhuntersAPI, 5 * 60 * 1000);

Getting Help

If you notice unusual patterns in your logs or need assistance with monitoring:

Check the documentation: Review the errors guide for common issues
Contact support: Email support@mindhunters.ai with log IDs for specific issues
Community forum: Ask questions in the developer community

Next Steps

Error Handling

Learn about error codes and troubleshooting

Webhooks

Set up webhook monitoring

API Reference

Explore all available endpoints

Authentication

Manage API tokens and security

​Overview

​Accessing Logs

​API Logs

​What’s Included

​Viewing API Log Details

​Example API Log Entry

​Webhook Logs

​What’s Included

​Viewing Webhook Log Details

​Example Webhook Log Entry

​Monitoring Best Practices

​Understanding Log Retention

​Common Monitoring Scenarios

​Debugging Failed API Calls

​Troubleshooting Webhook Deliveries

​Monitoring API Performance

​Exporting Logs

​API Metrics Dashboard

​Available Metrics

Request Volume

Success Rate

Average Response Time

Error Rate

Webhook Delivery Rate

Top Endpoints

​Rate Limits and Quotas

​Checking Your Usage

​Advanced Monitoring

​External Monitoring

​Log Aggregation

​Health Checks

​Getting Help

​Next Steps

Error Handling

Webhooks

API Reference

Authentication

Overview

Accessing Logs

API Logs

What’s Included

Viewing API Log Details

Example API Log Entry

Webhook Logs

What’s Included

Viewing Webhook Log Details

Example Webhook Log Entry

Monitoring Best Practices

Understanding Log Retention

Common Monitoring Scenarios

Debugging Failed API Calls

Troubleshooting Webhook Deliveries

Monitoring API Performance

Exporting Logs

API Metrics Dashboard

Available Metrics

Rate Limits and Quotas

Checking Your Usage

Advanced Monitoring

External Monitoring

Log Aggregation

Health Checks

Getting Help

Next Steps