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

# Activity Logs

> Track every action in your organization: webhooks, tool calls, API requests, agent changes, and call lifecycle events. Search, filter, and analyze with full-text search and aggregations.

Track what happened, when, and why. Activity logs capture every significant event across your organization — from webhook deliveries to tool executions to agent configuration changes.

**What you'll learn:** How to search and filter activity logs, understand event types and severities, and use the API for programmatic access.

***

## Access activity logs

<Tabs>
  <Tab title="Dashboard">
    Navigate to **Activity Logs** in the sidebar to view all events across your organization.
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch(
      'https://blackbox.dasha.ai/api/v1/activity-logs/search',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          page: 0,
          size: 50,
          sortDirection: 'Descending'
        })
      }
    ).then(r => r.json());

    console.log(`Total events: ${response.totalCount}`);
    response.results.forEach(event => {
      console.log(`[${event.severity}] ${event.type}: ${event.message}`);
    });
    ```
  </Tab>
</Tabs>

***

## Event types

Activity logs capture events across four categories:

### Agent lifecycle

| Type             | Description                            |
| ---------------- | -------------------------------------- |
| **AgentCreated** | A new agent was created                |
| **AgentUpdated** | An existing agent was updated          |
| **AgentDeleted** | An agent was deleted                   |
| **AgentCloned**  | An agent was cloned from another agent |

### Conversation lifecycle

| Type                      | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| **CallCreated**           | A conversation was created via REST API or WebSocket      |
| **CallBulkScheduled**     | A bulk batch of conversations was scheduled               |
| **CallCanceled**          | A conversation was canceled                               |
| **CallCompleted**         | A conversation completed successfully                     |
| **CallFailed**            | A conversation failed                                     |
| **CallDeadlineExceeded**  | A conversation exceeded its deadline                      |
| **CallDispatched**        | A conversation was dispatched to the runner for execution |
| **CallReceived**          | An incoming call was received                             |
| **CallRejectedByWebhook** | A conversation was rejected by the start webhook          |

### Webhooks

| Type               | Description                          |
| ------------------ | ------------------------------------ |
| **WebhookSuccess** | A webhook was delivered successfully |
| **WebhookFailed**  | A webhook delivery failed            |

### Runtime events

| Type                | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **ToolCallSuccess** | A tool call executed successfully during a conversation |
| **ToolCallFailed**  | A tool call failed during a conversation                |
| **McpCallExecuted** | An MCP (Model Context Protocol) call was executed       |

### Configuration changes

| Type                     | Description                                                              |
| ------------------------ | ------------------------------------------------------------------------ |
| **ConfigurationCreated** | A configuration resource was created (provider, SIP, media, integration) |
| **ConfigurationUpdated** | A configuration resource was updated                                     |
| **ConfigurationDeleted** | A configuration resource was deleted                                     |

***

## Severity levels

Each event has a severity level indicating its importance:

| Severity     | Description                                        | Examples                                    |
| ------------ | -------------------------------------------------- | ------------------------------------------- |
| **Info**     | Normal operation, no action required               | Successful webhook delivery, call completed |
| **Warning**  | Something unusual happened but operation continued | Slow webhook response, retry succeeded      |
| **Error**    | An operation failed                                | Webhook timeout, tool call error            |
| **Critical** | Severe failure requiring immediate attention       | Authentication failure, system unavailable  |

***

## Caller types

Events track who initiated the action:

| Caller     | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| **User**   | Action initiated by a user via API, dashboard, or web interface            |
| **System** | Action initiated by the platform (scheduler, webhooks, internal processes) |

***

## Filter activity logs

### By event type

Filter to specific event types to focus your analysis:

<Accordion title="Filter by type">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        types: ['WebhookFailed', 'ToolCallFailed'],
        size: 50
      })
    }
  ).then(r => r.json());

  console.log(`Failed events: ${response.totalCount}`);
  ```
</Accordion>

### By severity

Focus on errors and critical issues:

<Accordion title="Filter by severity">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        severities: ['Error', 'Critical'],
        size: 100
      })
    }
  ).then(r => r.json());

  response.results.forEach(event => {
    console.log(`[${event.severity}] ${event.message}`);
    if (event.metadata) {
      console.log('  Details:', JSON.stringify(event.metadata, null, 2));
    }
  });
  ```
</Accordion>

### By date range

Query events within a specific time window:

<Accordion title="Filter by date range">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fromDate: '2026-04-01T00:00:00Z',
        toDate: '2026-04-15T23:59:59Z',
        size: 100
      })
    }
  ).then(r => r.json());

  console.log(`Events in range: ${response.totalCount}`);
  ```
</Accordion>

### By agent or call

Track events for a specific agent or call:

<Accordion title="Filter by agent">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        agentIds: ['YOUR_AGENT_ID'],
        size: 50
      })
    }
  ).then(r => r.json());
  ```
</Accordion>

<Accordion title="Filter by call">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        callIds: ['YOUR_CALL_ID'],
        size: 50
      })
    }
  ).then(r => r.json());
  ```
</Accordion>

### Full-text search

Search across event messages and metadata:

<Accordion title="Text search">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        searchText: 'timeout',
        size: 50
      })
    }
  ).then(r => r.json());

  console.log(`Events mentioning "timeout": ${response.totalCount}`);
  ```
</Accordion>

***

## Aggregations

Search results include aggregated counts for quick analysis. These show how events break down by type, severity, and caller across all matching results — not just the current page.

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(
  'https://blackbox.dasha.ai/api/v1/activity-logs/search',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      fromDate: '2026-04-01T00:00:00Z',
      toDate: '2026-04-15T23:59:59Z',
      size: 0  // Only get aggregations, no results
    })
  }
).then(r => r.json());

console.log('By type:', response.aggregations?.typeCounts);
// { WebhookSuccess: 1523, ToolCallSuccess: 892, CallCompleted: 456, ... }

console.log('By severity:', response.aggregations?.severityCounts);
// { Info: 2800, Warning: 45, Error: 12, Critical: 1 }

console.log('By caller:', response.aggregations?.callerCounts);
// { System: 2750, User: 108 }
```

***

## API response structure

### Search activity logs

**Request:** `POST /api/v1/activity-logs/search`

**Request body:**

| Field           | Type                     | Default     | Description                     |
| --------------- | ------------------------ | ----------- | ------------------------------- |
| `page`          | integer                  | 0           | Page number (0-indexed)         |
| `size`          | integer                  | 20          | Results per page (max 100)      |
| `types`         | ActivityEventType\[]     | —           | Filter by event types           |
| `severities`    | ActivityEventSeverity\[] | —           | Filter by severity levels       |
| `callers`       | ActivityEventCaller\[]   | —           | Filter by caller (User, System) |
| `userEmail`     | string                   | —           | Filter by user email            |
| `callIds`       | string\[]                | —           | Filter by call IDs              |
| `agentIds`      | string\[]                | —           | Filter by agent IDs             |
| `fromDate`      | DateTimeOffset           | —           | Start of date range             |
| `toDate`        | DateTimeOffset           | —           | End of date range               |
| `searchText`    | string                   | —           | Full-text search query          |
| `sortField`     | string                   | "timestamp" | Field to sort by                |
| `sortDirection` | SortDirection            | Descending  | Ascending or Descending         |

<Accordion title="Response example">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "results": [
      {
        "eventId": "evt_abc123",
        "orgId": "org_xyz",
        "userEmail": null,
        "type": "WebhookSuccess",
        "severity": "Info",
        "callId": "call_def456",
        "agentId": "agent_ghi789",
        "message": "Webhook delivered successfully to https://api.example.com/webhook",
        "caller": "System",
        "metadata": {
          "url": "https://api.example.com/webhook",
          "statusCode": 200,
          "responseTimeMs": 145
        },
        "timestamp": "2026-04-15T10:30:00Z"
      },
      {
        "eventId": "evt_def456",
        "orgId": "org_xyz",
        "userEmail": "developer@company.com",
        "type": "AgentUpdated",
        "severity": "Info",
        "callId": null,
        "agentId": "agent_ghi789",
        "message": "Agent configuration updated",
        "caller": "User",
        "metadata": {
          "changedFields": ["systemPrompt", "ttsConfig"]
        },
        "timestamp": "2026-04-15T10:25:00Z"
      }
    ],
    "totalCount": 2858,
    "page": 0,
    "size": 20,
    "totalPages": 143,
    "aggregations": {
      "typeCounts": {
        "WebhookSuccess": 1523,
        "CallCompleted": 456,
        "ToolCallSuccess": 892
      },
      "severityCounts": {
        "Info": 2800,
        "Warning": 45,
        "Error": 12,
        "Critical": 1
      },
      "callerCounts": {
        "System": 2750,
        "User": 108
      }
    },
    "executionTimeMs": 23
  }
  ```
</Accordion>

***

## Common tasks

<Accordion title="Find all failed webhooks">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        types: ['WebhookFailed'],
        sortDirection: 'Descending',
        size: 50
      })
    }
  ).then(r => r.json());

  response.results.forEach(event => {
    console.log(`Call ${event.callId}: ${event.message}`);
    if (event.metadata) {
      console.log(`  URL: ${event.metadata.url}`);
      console.log(`  Error: ${event.metadata.error || event.metadata.statusCode}`);
    }
  });
  ```
</Accordion>

<Accordion title="Debug a specific call">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Get all events for a specific call
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        callIds: ['YOUR_CALL_ID'],
        sortField: 'timestamp',
        sortDirection: 'Ascending',
        size: 100
      })
    }
  ).then(r => r.json());

  // Timeline of events
  response.results.forEach(event => {
    const time = new Date(event.timestamp).toISOString();
    console.log(`${time} [${event.type}] ${event.message}`);
  });
  ```
</Accordion>

<Accordion title="Monitor tool call failures">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        types: ['ToolCallFailed'],
        fromDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), // Last 24h
        size: 100
      })
    }
  ).then(r => r.json());

  // Group by tool name
  const byTool = {};
  response.results.forEach(event => {
    const toolName = event.metadata?.toolName || 'unknown';
    byTool[toolName] = (byTool[toolName] || 0) + 1;
  });

  console.log('Tool failures by name:', byTool);
  ```
</Accordion>

<Accordion title="Track agent configuration changes">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://blackbox.dasha.ai/api/v1/activity-logs/search',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        types: ['AgentCreated', 'AgentUpdated', 'AgentDeleted'],
        callers: ['User'],
        size: 50
      })
    }
  ).then(r => r.json());

  response.results.forEach(event => {
    console.log(`${event.userEmail} ${event.type} agent ${event.agentId}`);
    if (event.metadata?.changedFields) {
      console.log(`  Changed: ${event.metadata.changedFields.join(', ')}`);
    }
  });
  ```
</Accordion>

***

## Troubleshooting with activity logs

Activity logs are your first stop when debugging issues. Here's how to approach common problems:

### Webhook not triggering?

1. Search for `WebhookFailed` events for your agent
2. Check the `metadata` field for error details (timeout, DNS failure, HTTP status)
3. Verify webhook URL is publicly accessible

### Tool calls failing silently?

1. Filter by `types: ['ToolCallFailed']` and your call ID
2. Review error messages and response times in metadata
3. Check if the tool webhook is responding within the 10-second timeout

### Unexpected call behavior?

1. Get the full event timeline for the call ID (sort ascending by timestamp)
2. Look for warning or error severity events
3. Check if `CallRejectedByWebhook` or `CallFailed` events explain the issue

<Note>
  Activity logs are retained for 90 days. For longer retention or compliance requirements, export logs periodically using the search API.
</Note>

***

## What's next

<CardGroup cols={2}>
  <Card title="Call History" icon="clock-rotate-left" href="/docs/monitor/call-history">
    View and search past calls
  </Card>

  <Card title="Call Inspector" icon="magnifying-glass" href="/docs/test/call-inspector">
    Deep dive into individual calls
  </Card>

  <Card title="Webhook Events" icon="webhook" href="/docs/webhooks-and-events/webhook-events">
    Understand webhook payloads
  </Card>

  <Card title="Testing Webhooks" icon="flask" href="/docs/webhooks-and-events/testing-webhooks">
    Test webhook delivery
  </Card>
</CardGroup>