> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mindhunters.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring & Logs

> Track your API requests, responses, and webhook deliveries in real-time

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

<Steps>
  <Step title="Log in to your workspace">
    Navigate to your Mindhunters workspace at `https://your-tenant.mindhunters.ai` and sign in.
  </Step>

  <Step title="Open the Logs panel">
    Click on **"Logs"** in the right section of your dashboard navigation.
  </Step>

  <Step title="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
  </Step>
</Steps>

## API Logs

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

### What's Included

Each API log entry contains:

<ParamField path="Timestamp" type="datetime">
  Exact date and time when the request was received
</ParamField>

<ParamField path="Method" type="string">
  HTTP method used (GET, POST, PATCH, DELETE)
</ParamField>

<ParamField path="Endpoint" type="string">
  The API endpoint that was called (e.g., `/api/v1/call`)
</ParamField>

<ParamField path="Status Code" type="number">
  HTTP response status code (200, 400, 401, 422, 500, etc.)
</ParamField>

<ParamField path="Response Time" type="number">
  How long the request took to process (in milliseconds)
</ParamField>

<ParamField path="IP Address" type="string">
  Source IP address of the request
</ParamField>

<ParamField path="Request Headers" type="object">
  Headers included in the request (API tokens are masked for security)
</ParamField>

<ParamField path="Request Body" type="object">
  The payload sent with the request
</ParamField>

<ParamField path="Response Body" type="object">
  The response returned by the API
</ParamField>

<ParamField path="User Agent" type="string">
  Client application or library information
</ParamField>

### Viewing API Log Details

<Steps>
  <Step title="Navigate to API Logs">
    From the Logs panel, select **"API Logs"**.
  </Step>

  <Step title="Browse request history">
    View a chronological list of all API requests. The most recent requests appear at the top.
  </Step>

  <Step title="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.)
  </Step>

  <Step title="View request details">
    Click on any log entry to see complete request and response details.
  </Step>
</Steps>

### Example API Log Entry

```json theme={null}
{
  "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:

<ParamField path="Timestamp" type="datetime">
  When the webhook was sent
</ParamField>

<ParamField path="Event Type" type="string">
  The type of event (e.g., `conversation.end`, `intent.triggered`)
</ParamField>

<ParamField path="Webhook URL" type="string">
  Your endpoint URL that received the webhook
</ParamField>

<ParamField path="Status Code" type="number">
  HTTP status code returned by your endpoint
</ParamField>

<ParamField path="Response Time" type="number">
  How long your endpoint took to respond (in milliseconds)
</ParamField>

<ParamField path="Attempt Number" type="number">
  Which delivery attempt this was (1-5)
</ParamField>

<ParamField path="Payload" type="object">
  The complete webhook payload that was sent
</ParamField>

<ParamField path="Response Body" type="object">
  The response returned by your endpoint
</ParamField>

<ParamField path="Error Message" type="string">
  Any error message if the delivery failed
</ParamField>

### Viewing Webhook Log Details

<Steps>
  <Step title="Navigate to Webhook Logs">
    From the Logs panel, select **"Webhook Logs"**.
  </Step>

  <Step title="Browse delivery history">
    View all webhook delivery attempts in chronological order.
  </Step>

  <Step title="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
  </Step>

  <Step title="View delivery details">
    Click any log entry to see the full payload, response, and any error details.
  </Step>
</Steps>

### Example Webhook Log Entry

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Set up alerts for errors" icon="bell">
    Regularly check for 4xx and 5xx errors in API logs. Consider setting up external monitoring to alert you when error rates increase.
  </Accordion>

  <Accordion title="Monitor response times" icon="gauge-high">
    Watch for slow API responses. If response times consistently exceed 2-3 seconds, investigate potential issues with your requests or network.
  </Accordion>

  <Accordion title="Track webhook delivery success" icon="check">
    Ensure webhooks are being delivered successfully. Failed webhook deliveries may indicate issues with your endpoint.
  </Accordion>

  <Accordion title="Review failed webhook retries" icon="arrows-rotate">
    If webhooks are failing repeatedly, check your endpoint's error logs and ensure it's responding with 200 status codes.
  </Accordion>

  <Accordion title="Monitor API usage patterns" icon="chart-line">
    Track your API usage to understand patterns and plan for capacity. Watch for unusual spikes that might indicate issues.
  </Accordion>

  <Accordion title="Keep logs for compliance" icon="file-shield">
    Download and archive logs if you need to maintain records for compliance or audit purposes.
  </Accordion>
</AccordionGroup>

## Understanding Log Retention

<Info>
  **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.
</Info>

## Common Monitoring Scenarios

### Debugging Failed API Calls

<Steps>
  <Step title="Identify the failed request">
    Filter API logs by status code 4xx or 5xx to find failed requests.
  </Step>

  <Step title="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
  </Step>

  <Step title="Check error messages">
    The response body will contain specific error information to help you fix the issue.
  </Step>

  <Step title="Verify and retry">
    Correct the issue in your code and retry the request. Check logs to confirm success.
  </Step>
</Steps>

### Troubleshooting Webhook Deliveries

<Steps>
  <Step title="Check webhook logs">
    Open Webhook Logs and filter by failed deliveries.
  </Step>

  <Step title="Examine failure details">
    Look at:

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

  <Step title="Test your endpoint">
    Verify your webhook endpoint is:

    * Publicly accessible
    * Using HTTPS
    * Responding within 5 seconds
    * Returning 200 status code
  </Step>

  <Step title="Trigger test webhook">
    Use the "Send Test Event" feature in Developer settings to test your endpoint.
  </Step>
</Steps>

### Monitoring API Performance

Regular monitoring helps you identify performance issues early:

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

## Exporting Logs

You can export logs for external analysis or compliance:

<Steps>
  <Step title="Filter logs">
    Use filters to select the logs you want to export.
  </Step>

  <Step title="Select export format">
    Choose your preferred format:

    * **JSON**: For programmatic analysis
    * **CSV**: For spreadsheet analysis
  </Step>

  <Step title="Download">
    Click **"Export"** and save the file to your device.
  </Step>
</Steps>

## API Metrics Dashboard

The Mindhunters dashboard provides visual metrics for your API usage:

### Available Metrics

<CardGroup cols={2}>
  <Card title="Request Volume" icon="chart-column">
    Total API requests over time, broken down by endpoint
  </Card>

  <Card title="Success Rate" icon="percent">
    Percentage of successful requests (2xx status codes)
  </Card>

  <Card title="Average Response Time" icon="clock">
    Mean response time for API requests
  </Card>

  <Card title="Error Rate" icon="triangle-exclamation">
    Percentage of failed requests (4xx and 5xx)
  </Card>

  <Card title="Webhook Delivery Rate" icon="webhook">
    Success rate for webhook deliveries
  </Card>

  <Card title="Top Endpoints" icon="ranking-star">
    Most frequently called API endpoints
  </Card>
</CardGroup>

## Rate Limits and Quotas

Monitor your usage against rate limits:

<Info>
  **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.
</Info>

### Checking Your Usage

View your current usage in the dashboard:

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

<Warning>
  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.
</Warning>

## 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:

```javascript Example Health Check theme={null}
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](/errors) for common issues
* **Contact support**: Email [support@mindhunters.ai](mailto:support@mindhunters.ai) with log IDs for specific issues
* **Community forum**: Ask questions in the developer community

## Next Steps

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/errors">
    Learn about error codes and troubleshooting
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Set up webhook monitoring
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore all available endpoints
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Manage API tokens and security
  </Card>
</CardGroup>