retell_list_calls
List and filter voice or chat agent calls by agent, status, time range, or type with pagination support for efficient call management.
Instructions
List and filter calls with pagination support. Can filter by agent, status, time range, and more.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter_criteria | No | Optional filter criteria | |
| limit | No | Number of results to return (default: 50, max: 1000) | |
| pagination_key | No | Pagination key from previous response for fetching next page | |
| sort_order | No | Sort order by start timestamp |
Implementation Reference
- src/index.ts:1129-1130 (handler)Handler case for retell_list_calls tool: Makes a POST request to the Retell API endpoint /v2/list-calls using the provided arguments.case "retell_list_calls": return retellRequest("/v2/list-calls", "POST", args);
- src/index.ts:128-160 (schema)Input schema definition for the retell_list_calls tool, specifying parameters like filter_criteria, limit, pagination_key, and sort_order.{ name: "retell_list_calls", description: "List and filter calls with pagination support. Can filter by agent, status, time range, and more.", inputSchema: { type: "object", properties: { filter_criteria: { type: "object", description: "Optional filter criteria", properties: { agent_id: { type: "array", items: { type: "string" }, description: "Filter by agent IDs" }, call_type: { type: "array", items: { type: "string" }, description: "Filter by call type (phone_call, web_call)" }, call_status: { type: "array", items: { type: "string" }, description: "Filter by status (registered, ongoing, ended, error)" }, start_timestamp_gte: { type: "integer", description: "Filter calls starting after this Unix timestamp" }, start_timestamp_lte: { type: "integer", description: "Filter calls starting before this Unix timestamp" } } }, limit: { type: "integer", description: "Number of results to return (default: 50, max: 1000)" }, pagination_key: { type: "string", description: "Pagination key from previous response for fetching next page" }, sort_order: { type: "string", enum: ["ascending", "descending"], description: "Sort order by start timestamp" } } } },
- src/index.ts:1283-1285 (registration)Registers the list of available tools, including retell_list_calls, via the ListToolsRequestSchema handler.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });
- src/index.ts:1287-1313 (registration)Registers the general tool execution handler (CallToolRequestSchema) which dispatches to executeTool based on tool name, handling retell_list_calls.// Register tool execution handler server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { const result = await executeTool(name, args as Record<string, unknown>); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error: ${errorMessage}`, }, ], isError: true, }; } });
- src/index.ts:23-57 (helper)Generic helper function retellRequest used by retell_list_calls handler to make authenticated API calls to Retell AI.async function retellRequest( endpoint: string, method: string = "GET", body?: Record<string, unknown> ): Promise<unknown> { const apiKey = getApiKey(); const headers: Record<string, string> = { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json", }; const options: RequestInit = { method, headers, }; if (body && method !== "GET") { options.body = JSON.stringify(body); } const response = await fetch(`${RETELL_API_BASE}${endpoint}`, options); if (!response.ok) { const errorText = await response.text(); throw new Error(`Retell API error (${response.status}): ${errorText}`); } // Handle 204 No Content if (response.status === 204) { return { success: true }; } return response.json(); }