retell_list_calls
Retrieve and filter call records by agent, status, time range, or type with pagination support for managing voice and chat interactions.
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 in executeTool function that implements retell_list_calls by making a POST request to Retell API /v2/list-calls with the input arguments.case "retell_list_calls": return retellRequest("/v2/list-calls", "POST", args);
- src/index.ts:128-160 (registration)Tool registration in the tools array, defining name, description, and input schema for retell_list_calls.{ 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:131-159 (schema)Input schema defining parameters for filtering, pagination, and sorting calls.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:23-57 (helper)Shared helper function that performs authenticated HTTP requests to the Retell API, handling authentication, JSON serialization, error handling, and response parsing. Used by the retell_list_calls handler.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(); }