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

# Observability

> Monitor and analyze your ElevenLabs-based voice agents

## Overview

This guide walks you through setting up and monitoring your ElevenLabs-based voice agents using Cekura's observability suite. Learn how to configure your integration and access powerful monitoring tools.

> [tab] Auto-fetch
>
> Auto-fetch pulls your call data from ElevenLabs every 30 seconds—no webhook configuration required.
>
> **1. Create or select an agent**
>
> In your Cekura dashboard, create a new agent or select an existing one with ElevenLabs as the voice provider.
>
> **2. Add credentials to Cekura**
>
> In the Agent Settings page:
>
> 1. Select **ElevenLabs** as the voice integration provider
> 2. Add your ElevenLabs API key
> 3. Enter your ElevenLabs Agent ID
>
> **3. Enable auto-fetch**
>
> Toggle on **Auto-fetch Production Calls** in the voice integration settings.
>
> **4. Test your integration**
>
> Make a test call from ElevenLabs. Within 30 seconds, your call should appear in the Cekura observability `Calls` section.
>
> > [!TIP]
> >
> > Auto-fetch is ideal for getting started quickly or when you can't configure webhooks. For real-time call data, use the webhook-based setup.
>
> > [!NOTE]
> >
> > If your ElevenLabs workspace has **Zero Retention Mode** on, auto-fetch only gets redacted transcripts and no recordings. Use the **Post-call webhook** tab instead.

> [tab] Post-call webhook
>
> ElevenLabs sends each call to Cekura as soon as it ends. Use this setup if your workspace has **Zero Retention Mode** on: ElevenLabs doesn't keep readable transcripts or recordings, so the webhook is the only way to get them.
>
> **1. Create the webhook in ElevenLabs**
>
> In ElevenLabs, go to **Developers → Webhooks** and click **Add endpoint**:
>
> 1. Enter the Cekura webhook URL:
>
>    ```
>    https://api.cekura.ai/observability/v1/elevenlabs/observe/
>    ```
>
> 2. Choose **HMAC** as the authentication method.
>
> 3. Save, and copy the webhook secret ElevenLabs shows you.
>
> **2. Send your agent's calls to the webhook**
>
> In the ElevenLabs agents platform, open **Settings**, click **Select Webhook** under **Post-Call Webhook**, and pick the webhook you created. To get recordings as well as transcripts, turn on **Send audio data**.
>
> ![ElevenLabs post-call webhook settings](https://mintcdn.com/vocera/-ehbdLduj39oRXOg/images/elevenlabs-observe.png?fit=max\&auto=format\&n=-ehbdLduj39oRXOg\&q=85\&s=63e402d5a616bbade8afa73f9656f73c)
>
> > [!TIP]
> >
> > This setting covers every agent in the workspace. To send only some agents' calls, select the webhook in each of those agents' settings instead.
>
> **3. Add the secret to your agent in Cekura**
>
> In your Cekura Agent Settings page, with **ElevenLabs** as the voice integration provider:
>
> 1. Make sure your ElevenLabs API key and Agent ID are filled in.
> 2. Paste the secret into **Post-call Webhook Secret** and save.
>
>    ![ElevenLabs Agent Settings](https://mintcdn.com/vocera/TwfRd5EQeiW9Y10g/images/elevenlabs/agent-settings.png?fit=max\&auto=format\&n=TwfRd5EQeiW9Y10g\&q=85\&s=137691791557d09190dd54835cd2f55c)
>
> Add the secret to every Cekura agent that should receive these calls. The secret is set per agent, so agents connected to different ElevenLabs workspaces, such as staging and production, can each use their own webhook.
>
> **4. Test your integration**
>
> Make a test call to your ElevenLabs agent. Within a minute, it should appear in the Cekura observability `Calls` section with its transcript and, if **Send audio data** is on, its recording.
>
> > [!NOTE]
> >
> > Once an agent has a webhook secret, Cekura stops auto-fetching its calls. You don't need to turn off **Auto-fetch Production Calls**.
>
> > [accordion] Calls don't appear in Cekura
> >
> > * Check that the secret in Cekura matches the webhook in ElevenLabs. If you're not sure, create a new webhook and paste its secret.
> > * Check that the Agent ID in Cekura matches your ElevenLabs agent.
> > * ElevenLabs turns off webhooks that keep failing. Make sure the webhook is still enabled under **Developers → Webhooks**.
>
> > [accordion] Calls appear without a recording
> >
> > Turn on **Send audio data** in ElevenLabs. Text-only conversations never have a recording.

> [tab] Forwarding ElevenLabs response
>
> If you already have an existing webhook setup and want to forward the ElevenLabs response to Cekura's observability suite:
>
> **1. Configure forwarding endpoint**
>
> Set up a forwarding mechanism to send the ElevenLabs webhook response to Cekura's observability endpoint:
>
> ```
> POST https://api.cekura.ai/observability/v1/observe/
> ```
>
> **2. Add authentication headers**
>
> Include your Cekura API key in the request headers:
>
> ```
> X-CEKURA-API-KEY: <your_cekura_api_key>
> Content-Type: multipart/form-data
> ```
>
> **3. Forward the request body**
>
> Forward the ElevenLabs webhook response to Cekura with the following request body structure:
>
> ```json theme={null}
> {
>   "agent": <agent_id_in_cekura>,
>   "transcript_type": "elevenlabs",
>   "transcript_json": elevenlabs_response["transcript"],
>   "call_id": elevenlabs_response["conversation_id"],
>   "voice_recording": <binary_audio_file>
> }
> ```
>
> > [!NOTE]
> >
> > You should first download the audio data from the ElevenLabs API using the conversation ID, then pass this binary audio data to the Cekura Observe API as shown in the code examples below.

***

## Advanced: Code Implementation Examples

### Downloading Call Audio from ElevenLabs

You can download call audio recordings directly from ElevenLabs using their API. Here's a Python snippet that demonstrates how to retrieve call audio using the conversation ID and your ElevenLabs API key:

```python theme={null}
import requests
from typing import Optional, Union, Dict, Any, List, bytes

# configuration variables
ELEVENLABS_API_KEY = "your_elevenlabs_api_key"

ELEVENLABS_API_BASE_URL = "https://api.elevenlabs.io/v1"

def download_elevenlabs_call_audio(conversation_id: str, output_file: Optional[str] = None) -> Union[bytes, bool, None]:
    """
    Download call audio recording from ElevenLabs API.
    
    Args:
        conversation_id (str): The ElevenLabs conversation ID
        output_file (str, optional): Path to save the audio file. If None, returns the audio content
                                     without saving to file.
    
    Returns:
        Union[bytes, bool, None]: If output_file is None, returns the audio content as bytes.
                                 If output_file is provided, returns True if successful.
                                 Returns None if the request fails.
    """
    # API endpoint for retrieving conversation audio
    url = f"{ELEVENLABS_API_BASE_URL}/convai/conversations/{conversation_id}/audio"
    
    # Set up headers with API key
    headers = {
        "xi-api-key": ELEVENLABS_API_KEY,
    }
    
    # Make the request to ElevenLabs API
    response = requests.get(url, headers=headers)
    
    # Check if the request was successful
    if response.status_code == 200:
        # If output file is provided, save the file
        if output_file:
            with open(output_file, 'wb') as f:
                f.write(response.content)
            return True
        
        # Otherwise return the audio content
        return response.content
    else:
        print(f"Error: {response.status_code}")
        print(response.text)
        return None

# Example usage:
# conversation_id = "your_conversation_id"
# 
# # Download and save to a file
# download_elevenlabs_call_audio(conversation_id, "call_recording.mp3")
# 
# # Or just get the audio content without saving
# audio_content = download_elevenlabs_call_audio(conversation_id)
```

### Sending Call Data to Cekura's Observability API

After downloading the audio from ElevenLabs, you can send it along with the transcript data to Cekura's observability API. Here's how to do it:

```python theme={null}
import requests
import json
from typing import Optional, Dict, Any, List, Union

# configuration variables
ELEVENLABS_API_KEY = "your_elevenlabs_api_key"
CEKURA_API_KEY = "your_cekura_api_key"
CEKURA_AGENT_ID = "your_cekura_agent_id"


CEKURA_API_BASE_URL = "https://api.cekura.ai"
ELEVENLABS_API_BASE_URL = "https://api.elevenlabs.io/v1"

def send_to_cekura_observe(conversation_id: str, transcript_data: List[Dict[str, Any]], 
                           audio_content: bytes) -> Optional[Dict[str, Any]]:
    """
    Send ElevenLabs call data to Cekura's observability API.
    
    Args:
        conversation_id (str): The ElevenLabs conversation ID
        transcript_data (List[Dict[str, Any]]): The transcript data from ElevenLabs
        audio_content (bytes): The audio content downloaded from ElevenLabs
        
    Returns:
        Optional[Dict[str, Any]]: The response from the Cekura API or None if request failed
    """
    # Cekura observability API endpoint
    url = f"{CEKURA_API_BASE_URL}/observability/v1/observe/"
    
    # Set up headers with Cekura API key
    headers = {
        "X-CEKURA-API-KEY": CEKURA_API_KEY
    }
    
    # Prepare the data payload
    data = {
        "agent": CEKURA_AGENT_ID,
        "call_id": conversation_id,
        "transcript_type": "elevenlabs",
        "transcript_json": json.dumps(transcript_data)
    }
    
    # Prepare the files payload with the audio content
    files = {
        "voice_recording": (f"elevenlabs_recording_{conversation_id}.mp3", audio_content, "audio/mpeg")
    }
    
    # Make the request to Cekura API
    response = requests.post(url, headers=headers, data=data, files=files)
    
    # Check if the request was successful
    if response.status_code == 201:
        return response.json()
    else:
        print(f"Error: {response.status_code}")
        print(response.text)
        return None

# Example usage:
# conversation_id = "your_conversation_id"
#
# # First download the audio from ElevenLabs
# audio_content = download_elevenlabs_call_audio(conversation_id)
#
# # Get the transcript data from ElevenLabs (this would come from your webhook or API call)
# transcript_data = [...]  # Your ElevenLabs transcript data

# # Send everything to Cekura
# if audio_content:
#     result = send_to_cekura_observe(conversation_id, transcript_data, audio_content)
#     print(f"Call log created with ID: {result['id']}")
```

### Extracting Agent Description from Workflows

If your ElevenLabs agent uses workflows, you can extract the complete agent description including system prompts, workflow nodes, and transfer conditions. This is useful for understanding your agent's structure when setting up observability and monitoring.

#### Usage

Run the script with your agent ID and ElevenLabs API key:

```bash theme={null}
python script.py <AGENT_ID> <11LABS_API_KEY>
```

#### Script

```python theme={null}
# python script.py <AGENT_ID> <11LABS_API_KEY>

import requests
import json
import argparse

def get_agent_description(agent_id: str, api_key: str) -> list | None:
    api_url = f"https://api.elevenlabs.io/v1/convai/agents/{agent_id}"
    headers = {
        "Content-Type": "application/json",
        "xi-api-key": api_key
    }

    try:
        print(f"Fetching data for agent ID: {agent_id}...")
        response = requests.get(api_url, headers=headers)
        response.raise_for_status()
        data = response.json()
        print("Successfully fetched data.")
    except requests.exceptions.RequestException as e:
        print(f"Error: Failed to fetch data from API. {e}")
        return None

    agent_description = []

    try:
        system_prompt = data['conversation_config']['agent']['prompt']['prompt']
        agent_description.append({
            "node name": "system",
            "node prompt": system_prompt
        })
    except KeyError:
        print("Warning: Could not find the main system prompt.")
        agent_description.append({
            "node name": "system",
            "node prompt": "Prompt not found in API response."
        })

    workflow = data.get('workflow', {})
    if not workflow:
        print("No workflow found for this agent.")
        return agent_description

    nodes = workflow.get('nodes', {})
    edges = workflow.get('edges', {})

    for node_id, node_data in nodes.items():
        if node_data.get('type') == 'start':
            continue

        node_name = node_data.get('label', 'Unnamed Node')
        node_prompt = node_data.get('additional_prompt', '')
        transfer_conditions = []

        if edges:
            for edge_data in edges.values():
                if edge_data.get('target') == node_id:
                    fwd_cond = edge_data.get('forward_condition')
                    if fwd_cond and fwd_cond.get('type') != 'unconditional':
                        condition_text = fwd_cond.get('condition') or fwd_cond.get('label')
                        if condition_text:
                            transfer_conditions.append(condition_text)

                    bwd_cond = edge_data.get('backward_condition')
                    if bwd_cond:
                        condition_text = bwd_cond.get('condition') or bwd_cond.get('label')
                        if condition_text:
                            transfer_conditions.append(condition_text)

        agent_description.append({
            "node name": node_name,
            "node prompt": node_prompt,
            "transfer conditions": transfer_conditions
        })

    return agent_description

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Fetch and format agent data from the Eleven Labs API.")
    parser.add_argument("agent_id", type=str, help="The ID of the Eleven Labs agent to query.")
    parser.add_argument("api_key", type=str, help="Your Eleven Labs API key.")

    args = parser.parse_args()

    description = get_agent_description(args.agent_id, args.api_key)

    if description:
        print("\n--- Generated Agent Description ---")
        print(json.dumps(description, indent=2))
        print("---------------------------------\n")
```

> [!NOTE]
>
> This script retrieves the agent's configuration from ElevenLabs, including the system prompt and all workflow nodes with their prompts and transfer conditions. The output is formatted as JSON and can be used to understand your agent's conversation flow when analyzing call logs in Cekura's observability suite.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.