get_lists
Retrieve and filter customer lists from Klaviyo with pagination controls to manage marketing audience data.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter query for lists | |
| page_size | No | Number of lists per page (1-100) | |
| page_cursor | No | Cursor for pagination |
Implementation Reference
- src/tools/lists.js:13-25 (handler)Handler function for the 'get_lists' tool. Fetches lists from Klaviyo API using the generic klaviyoClient.get method, formats the response as a JSON string in a text content block, and handles errors by returning an error message.async (params) => { try { const lists = await klaviyoClient.get('/lists/', params); return { content: [{ type: "text", text: JSON.stringify(lists, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error retrieving lists: ${error.message}` }], isError: true }; } },
- src/tools/lists.js:8-12 (schema)Zod schema defining the input parameters for the 'get_lists' tool: optional filter string, page_size (1-100), and page_cursor for pagination.{ filter: z.string().optional().describe("Filter query for lists"), page_size: z.number().min(1).max(100).optional().describe("Number of lists per page (1-100)"), page_cursor: z.string().optional().describe("Cursor for pagination") },
- src/tools/lists.js:6-27 (registration)Direct registration of the 'get_lists' tool using server.tool(), specifying the name, input schema, execution handler, and description.server.tool( "get_lists", { filter: z.string().optional().describe("Filter query for lists"), page_size: z.number().min(1).max(100).optional().describe("Number of lists per page (1-100)"), page_cursor: z.string().optional().describe("Cursor for pagination") }, async (params) => { try { const lists = await klaviyoClient.get('/lists/', params); return { content: [{ type: "text", text: JSON.stringify(lists, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error retrieving lists: ${error.message}` }], isError: true }; } }, { description: "Get lists from Klaviyo" } );
- src/server.js:33-33 (registration)Top-level invocation of registerListTools(server), which registers the 'get_lists' tool (and other list-related tools).registerListTools(server);
- src/klaviyo-client.js:135-180 (helper)Generic 'get' helper function used by the handler. Builds the API URL with query parameters (filter, page_size, page_cursor), performs the axios GET request via executeWithRetry (with caching, rate limiting retries), and handles Klaviyo-specific API formatting.export async function get(endpoint, params = {}, fallbackFn) { // Build the URL with query parameters according to Klaviyo API specs let url = endpoint; const queryParams = []; // Special handling for campaign endpoint - add required filter if missing if (endpoint === '/campaigns/' && !params.filter) { logger.debug('Adding default email filter for campaigns endpoint'); params.filter = "equals(messages.channel,'email')"; } // Handle filter parameter if provided if (params.filter) { queryParams.push(`filter=${encodeURIComponent(params.filter)}`); } // Handle include parameter if provided if (params.include) { queryParams.push(`include=${encodeURIComponent(params.include)}`); } // Handle page_size parameter if provided if (params.page_size) { queryParams.push(`page[size]=${params.page_size}`); } // Handle pagination cursor if provided if (params.page_cursor) { queryParams.push(`page[cursor]=${params.page_cursor}`); } // Add query parameters to URL if (queryParams.length > 0) { url = `${endpoint}?${queryParams.join('&')}`; } logger.debug(`Prepared GET request to: ${url}`); return executeWithRetry( () => client.get(url), 'GET', endpoint, params, fallbackFn ); }