list_saved_cohorts
Retrieve saved user cohorts from Mixpanel to discover existing segments and obtain cohort IDs for detailed analysis.
Instructions
List user cohorts in the project. Useful for discovering existing user segments and getting cohort IDs for analysis.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | The Mixpanel project ID. Optional since it has a default. |
Implementation Reference
- src/index.ts:1151-1198 (handler)The handler function that executes the tool logic by making a GET request to Mixpanel's /cohorts/list API endpoint with Basic Auth, returning the list of saved cohorts or an error.
async function handleListSavedCohorts(args: any, config: any) { const { project_id = config.DEFAULT_PROJECT_ID } = args; try { const credentials = `${config.SERVICE_ACCOUNT_USER_NAME}:${config.SERVICE_ACCOUNT_PASSWORD}`; const encodedCredentials = Buffer.from(credentials).toString('base64'); const url = `${config.MIXPANEL_BASE_URL}/cohorts/list?project_id=${project_id}`; const options = { method: 'GET', headers: { 'accept': 'application/json', 'authorization': `Basic ${encodedCredentials}` } }; const response = await fetch(url, options); if (!response.ok) { const errorText = await response.text(); throw new Error(`HTTP error! status: ${response.status} - ${errorText}`); } const data = await response.json(); return { content: [ { type: "text", text: JSON.stringify(data) } ] }; } catch (error: unknown) { console.error("Error listing saved cohorts:", error); const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error listing saved cohorts: ${errorMessage}` } ], isError: true }; } } - src/index.ts:498-510 (schema)The input schema definition for the list_saved_cohorts tool, specifying optional project_id parameter.
{ name: "list_saved_cohorts", description: "List user cohorts in the project. Useful for discovering existing user segments and getting cohort IDs for analysis.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." } } } }, - src/index.ts:632-637 (registration)The switch case registration in the CallToolRequestSchema handler that routes calls to list_saved_cohorts to the handleListSavedCohorts function.
case "list_saved_funnels": return await handleListSavedFunnels(args, { SERVICE_ACCOUNT_USER_NAME, SERVICE_ACCOUNT_PASSWORD, DEFAULT_PROJECT_ID, MIXPANEL_BASE_URL }); case "list_saved_cohorts": return await handleListSavedCohorts(args, { SERVICE_ACCOUNT_USER_NAME, SERVICE_ACCOUNT_PASSWORD, DEFAULT_PROJECT_ID, MIXPANEL_BASE_URL }); - src/index.ts:232-597 (registration)The tool is registered in the ListToolsRequestSchema handler's tools array for tool discovery.
return { tools: [ // Event Tools { name: "get_today_top_events", description: "Get today's top events from Mixpanel. Useful for quickly identifying the most active events happening today, spotting trends, and monitoring real-time user activity.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, type: { type: "string", enum: ["general", "average", "unique"], description: "The type of events to fetch, either general, average, or unique, defaults to general" }, limit: { type: "number", description: "Maximum number of events to return" } } } }, { name: "get_top_events", description: "Get a list of the most common events over the last 31 days. Useful for identifying key user actions, prioritizing feature development, and understanding overall platform usage patterns.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, type: { type: "string", enum: ["general", "average", "unique"], description: "The type of events to fetch, either general, average, or unique, defaults to general" }, limit: { type: "number", description: "Maximum number of events to return" } } } }, { name: "aggregate_event_counts", description: "Get event counts over time periods. Useful for analyzing event volume trends and identifying patterns in user activity over time.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, event: { type: "string", description: "The event name to get counts for" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, unit: { type: "string", enum: ["hour", "day", "week", "month"], description: "The time unit for aggregation, defaults to day" } }, required: ["event", "from_date", "to_date"] } }, { name: "aggregated_event_property_values", description: "Analyze specific event properties and their values. Useful for understanding property distributions and identifying common values.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, event: { type: "string", description: "The event name to analyze properties for" }, property: { type: "string", description: "The property name to get values for" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, limit: { type: "number", description: "Maximum number of property values to return" } }, required: ["event", "property", "from_date", "to_date"] } }, // User Profile Tools { name: "profile_event_activity", description: "Get data for a profile's event activity. Useful for understanding individual user journeys, troubleshooting user-specific issues, and analyzing behavior patterns of specific users.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, workspace_id: { type: "string", description: "The ID of the workspace if applicable" }, distinct_ids: { type: "string", description: "A JSON array as a string representing the distinct_ids to return activity feeds for. Example: [\"12a34aa567eb8d-9ab1c26f345b67-89123c45-6aeaa7-89f12af345f678\"]" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" } }, required: ["distinct_ids", "from_date", "to_date"] } }, { name: "query_profiles", description: "Query user profiles with filtering. Useful for finding users based on profile properties and analyzing user segments.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, where: { type: "string", description: "JSON string representing the filter conditions for profiles" }, select: { type: "string", description: "JSON array string of properties to return. If not specified, returns all properties" }, limit: { type: "number", description: "Maximum number of profiles to return" } } } }, // Analytics Tools { name: "query_retention_report", description: "Analyze user retention patterns. Useful for understanding how well you retain users over time and identifying cohort behavior.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, born_event: { type: "string", description: "The event that defines when users are 'born' for retention analysis" }, event: { type: "string", description: "The event to measure retention for (optional, defaults to any event)" }, born_where: { type: "string", description: "JSON string representing additional filters for the born event" }, where: { type: "string", description: "JSON string representing additional filters for the retention event" }, interval: { type: "string", enum: ["day", "week", "month"], description: "The time interval for retention analysis, defaults to day" }, interval_count: { type: "number", description: "Number of intervals to analyze, defaults to 30" } }, required: ["from_date", "to_date", "born_event"] } }, { name: "query_funnel_report", description: "Get funnel conversion data. Useful for analyzing conversion rates through multi-step user flows and identifying drop-off points.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, events: { type: "string", description: "JSON array string of events that make up the funnel steps" }, funnel_window: { type: "number", description: "Number of days users have to complete the funnel" }, interval: { type: "string", enum: ["day", "week", "month"], description: "The time interval for funnel analysis" } }, required: ["from_date", "to_date", "events"] } }, { name: "list_saved_funnels", description: "List available saved funnels in the project. Useful for discovering existing funnel analyses and getting funnel IDs for further analysis.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." } } } }, { name: "list_saved_cohorts", description: "List user cohorts in the project. Useful for discovering existing user segments and getting cohort IDs for analysis.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." } } } }, // Advanced Tools { name: "custom_jql", description: "Run custom JQL (JSON Query Language) queries. Useful for advanced analytics and custom data analysis beyond standard reports.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, script: { type: "string", description: "The JQL script to execute" } }, required: ["script"] } }, { name: "query_segmentation_report", description: "Segment events by properties. Useful for analyzing how different user segments behave and comparing event patterns across groups.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, event: { type: "string", description: "The event to segment" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, on: { type: "string", description: "The property to segment by" }, where: { type: "string", description: "JSON string representing additional filters" }, unit: { type: "string", enum: ["hour", "day", "week", "month"], description: "The time unit for segmentation, defaults to day" } }, required: ["event", "from_date", "to_date", "on"] } }, { name: "query_insights_report", description: "Get saved insights reports. Useful for accessing pre-configured analytics reports and dashboards.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, report_id: { type: "string", description: "The ID of the saved insights report to retrieve" }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" } }, required: ["report_id"] } } ] };