list_conversations
Retrieve and filter conversation history from ElevenLabs agents, enabling users to review past interactions and monitor audio processing activities with pagination and time-based filtering.
Instructions
Lists agent conversations. Returns: conversation list with metadata. Use when: asked about conversation history.
Args:
agent_id (str, optional): Filter conversations by specific agent ID
cursor (str, optional): Pagination cursor for retrieving next page of results
call_start_before_unix (int, optional): Filter conversations that started before this Unix timestamp
call_start_after_unix (int, optional): Filter conversations that started after this Unix timestamp
page_size (int, optional): Number of conversations to return per page (1-100, defaults to 30)
max_length (int, optional): Maximum character length of the response text (defaults to 10000)Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | No | ||
| call_start_after_unix | No | ||
| call_start_before_unix | No | ||
| cursor | No | ||
| max_length | No | ||
| page_size | No |
Implementation Reference
- elevenlabs_mcp/server.py:757-768 (registration)The @mcp.tool decorator registers the 'list_conversations' tool and provides the schema via parameter descriptions in the docstring.
@mcp.tool( description="""Lists agent conversations. Returns: conversation list with metadata. Use when: asked about conversation history. Args: agent_id (str, optional): Filter conversations by specific agent ID cursor (str, optional): Pagination cursor for retrieving next page of results call_start_before_unix (int, optional): Filter conversations that started before this Unix timestamp call_start_after_unix (int, optional): Filter conversations that started after this Unix timestamp page_size (int, optional): Number of conversations to return per page (1-100, defaults to 30) max_length (int, optional): Maximum character length of the response text (defaults to 10000) """ ) - elevenlabs_mcp/server.py:769-829 (handler)The core handler function that executes the tool: fetches conversations from ElevenLabs API, formats them with metadata, handles pagination, truncates large responses if needed, and returns formatted TextContent.
def list_conversations( agent_id: str | None = None, cursor: str | None = None, call_start_before_unix: int | None = None, call_start_after_unix: int | None = None, page_size: int = 30, max_length: int = 10000, ) -> TextContent: """List conversations with filtering options.""" page_size = min(page_size, 100) try: response = client.conversational_ai.conversations.list( cursor=cursor, agent_id=agent_id, call_start_before_unix=call_start_before_unix, call_start_after_unix=call_start_after_unix, page_size=page_size, ) if not response.conversations: return TextContent(type="text", text="No conversations found.") conv_list = [] for conv in response.conversations: start_time = datetime.fromtimestamp(conv.start_time_unix_secs).strftime( "%Y-%m-%d %H:%M:%S" ) conv_info = f"""Conversation ID: {conv.conversation_id} Status: {conv.status} Agent: {conv.agent_name or 'N/A'} (ID: {conv.agent_id}) Started: {start_time} Duration: {conv.call_duration_secs} seconds Messages: {conv.message_count} Call Successful: {conv.call_successful}""" conv_list.append(conv_info) formatted_list = "\n\n".join(conv_list) pagination_info = f"Showing {len(response.conversations)} conversations" if response.has_more: pagination_info += f" (more available, next cursor: {response.next_cursor})" full_text = f"{pagination_info}\n\n{formatted_list}" # Use utility to handle large text content result_text = handle_large_text(full_text, max_length, "conversation list") # If content was saved to file, prepend pagination info if result_text != full_text: result_text = f"{pagination_info}\n\n{result_text}" return TextContent(type="text", text=result_text) except Exception as e: make_error(f"Failed to list conversations: {str(e)}") # This line is unreachable but satisfies type checker return TextContent(type="text", text="")