query_segmentation_bucket
Analyze event data distributions by segmenting and filtering numeric properties into specified buckets. Create histograms and assess quantitative metrics over custom ranges for detailed insights.
Instructions
Get data for an event, segmented and filtered by properties, with values placed into numeric buckets. Useful for analyzing distributions of numeric values, creating histograms, and understanding the range of quantitative metrics.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | The event that you wish to get data for. Note: this is a single event name, not an array | |
| from_date | Yes | The date in yyyy-mm-dd format to begin querying from (inclusive) | |
| on | Yes | The property expression to segment the event on. This expression must be a numeric property | |
| project_id | No | The Mixpanel project ID. Optional since it has a default. | |
| to_date | Yes | The date in yyyy-mm-dd format to query to (inclusive) | |
| type | No | The type of analysis to perform, either general, unique, or average, defaults to general | |
| unit | No | The buckets into which the property values that you segment on are placed. Default is 'day' | |
| where | Yes | An expression to filter events by based on the grammar: <expression> ::= 'properties["' <property> '"]' | <expression> <binary op> <expression> | <unary op> <expression> | <math op> '(' <expression> ')' | <string literal> <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or' | <unary op> ::= '-' | 'not' | |
| workspace_id | No | The ID of the workspace if applicable |
Implementation Reference
- src/index.ts:1232-1317 (handler)The complete MCP tool definition for 'query_segmentation_bucket', including registration via server.tool(), Zod input schema, and the handler function that performs Basic auth fetch to Mixpanel's /api/query/segmentation/numeric endpoint.
server.tool( "query_segmentation_bucket", "Get data for an event, segmented and filtered by properties, with values placed into numeric buckets. Useful for analyzing distributions of numeric values, creating histograms, and understanding the range of quantitative metrics.", { project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(), workspace_id: z.string().describe("The ID of the workspace if applicable").optional(), event: z.string().describe("The event that you wish to get data for. Note: this is a single event name, not an array"), from_date: z.string().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"), to_date: z.string().describe("The date in yyyy-mm-dd format to query to (inclusive)"), on: z.string().describe("The property expression to segment the event on. This expression must be a numeric property"), unit: z.enum(["hour", "day"]).describe("The buckets into which the property values that you segment on are placed. Default is 'day'").optional(), where: z.string().describe(`An expression to filter events by based on the grammar: <expression> ::= 'properties["' <property> '"]' | <expression> <binary op> <expression> | <unary op> <expression> | <math op> '(' <expression> ')' | <string literal> <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or' | <unary op> ::= '-' | 'not'`), type: z.enum(["general", "unique", "average"]).describe("The type of analysis to perform, either general, unique, or average, defaults to general").optional(), }, async ({ project_id = DEFAULT_PROJECT_ID, workspace_id, event, from_date, to_date, on, unit, where, type }) => { try { // Create authorization header using base64 encoding of credentials const credentials = `${SERVICE_ACCOUNT_USER_NAME}:${SERVICE_ACCOUNT_PASSWORD}`; const encodedCredentials = Buffer.from(credentials).toString('base64'); // Construct base URL with required parameters let url = `https://mixpanel.com/api/query/segmentation/numeric?project_id=${project_id}&event=${encodeURIComponent(event)}&from_date=${from_date}&to_date=${to_date}&on=${encodeURIComponent(on)}`; // Add optional parameters if they exist if (workspace_id) url += `&workspace_id=${workspace_id}`; if (unit) url += `&unit=${unit}`; if (where) url += `&where=${encodeURIComponent(where)}`; if (type) url += `&type=${type}`; // Set up request options const options = { method: 'GET', headers: { 'accept': 'application/json', 'authorization': `Basic ${encodedCredentials}` } }; // Make the API request const response = await fetch(url, options); if (!response.ok) { const errorText = await response.text(); throw new Error(`API request failed with status ${response.status}: ${errorText}`); } const data = await response.json(); return { content: [ { type: "text", text: JSON.stringify(data) } ] }; } catch (error) { console.error('Error querying segmentation bucket:', error); return { content: [ { type: "text", text: `Error querying segmentation bucket: ${error}` } ], isError: true }; } } ); - src/index.ts:1235-1252 (schema)Zod schema for input validation of the query_segmentation_bucket tool parameters, mirroring the Mixpanel API requirements.
{ project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(), workspace_id: z.string().describe("The ID of the workspace if applicable").optional(), event: z.string().describe("The event that you wish to get data for. Note: this is a single event name, not an array"), from_date: z.string().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"), to_date: z.string().describe("The date in yyyy-mm-dd format to query to (inclusive)"), on: z.string().describe("The property expression to segment the event on. This expression must be a numeric property"), unit: z.enum(["hour", "day"]).describe("The buckets into which the property values that you segment on are placed. Default is 'day'").optional(), where: z.string().describe(`An expression to filter events by based on the grammar: <expression> ::= 'properties["' <property> '"]' | <expression> <binary op> <expression> | <unary op> <expression> | <math op> '(' <expression> ')' | <string literal> <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or' | <unary op> ::= '-' | 'not'`), type: z.enum(["general", "unique", "average"]).describe("The type of analysis to perform, either general, unique, or average, defaults to general").optional(), }, - JSON Schema definition for the underlying Mixpanel API endpoint /segmentation/numeric used by the tool (SegmentationNumericQuery).
declare const SegmentationNumericQuery: { readonly metadata: { readonly allOf: readonly [{ readonly type: "object"; readonly properties: { readonly project_id: { readonly type: "integer"; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "Required if using service account to authenticate request."; }; readonly workspace_id: { readonly type: "integer"; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "The id of the workspace if applicable."; }; readonly event: { readonly type: "string"; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "The event that you wish to get data for. Note: this is a single event name, not an array."; }; readonly from_date: { readonly type: "string"; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "The date in yyyy-mm-dd format to begin querying from. This date is inclusive."; }; readonly to_date: { readonly type: "string"; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "The date in yyyy-mm-dd format to query to. This date is inclusive."; }; readonly on: { readonly type: "string"; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "The property expression to segment the event on. This expression must be a numeric property. See the [expressions section](ref:segmentation-expressions) below."; }; readonly unit: { readonly type: "string"; readonly enum: readonly ["hour", "day"]; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "This can be \"hour\" or \"day\". This determines the buckets into which the property values that you segment on are placed. The default value is \"day\"."; }; readonly where: { readonly type: "string"; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "An expression to filter events by. See the [expression to segment](ref:segmentation-expressions) below."; }; readonly type: { readonly type: "string"; readonly enum: readonly ["general", "unique", "average"]; readonly $schema: "http://json-schema.org/draft-04/schema#"; readonly description: "This can be \"hour\" or \"day\". This determines the buckets into which the property values that you segment on are placed. The default value is \"day\"."; }; }; readonly required: readonly ["project_id", "event", "from_date", "to_date", "on"]; }]; }; readonly response: { readonly "200": { readonly type: "object"; readonly properties: { readonly data: { readonly type: "object"; readonly properties: { readonly series: { readonly type: "array"; readonly items: { readonly type: "string"; readonly description: "All dates we have data for in the response."; }; }; readonly values: { readonly type: "object"; readonly additionalProperties: { readonly type: "object"; readonly description: "The range of the bucket"; readonly additionalProperties: { readonly type: "integer"; readonly description: "A mapping of the date of each unit to the number of specified events that took place. (ex. {\"2010-05-30\": 6})"; }; }; }; }; }; readonly legend_size: { readonly type: "integer"; readonly description: "List of all dates."; }; }; readonly $schema: "http://json-schema.org/draft-04/schema#"; }; }; };