{"files":{"SKILL.md":"---\nname: query-api\ndescription: \"Query API skill. Use when working with Query for insights, funnels, retention. Covers 19 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Query API\nAPI version: 1.0.0\n\n## Auth\nNo authentication required.\n\n## Base URL\nhttps://mixpanel.com/api/query\n\n## Setup\n1. No auth setup needed\n2. GET /insights -- query saved report\n3. POST /cohorts/list -- create first list\n\n## Endpoints\n19 endpoints across 9 groups. See references/api-spec.lap for full details.\n\n### Insights\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /insights | Query Saved Report |\n\n### Funnels\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /funnels | Query Saved Report |\n| GET | /funnels/list | List Saved Funnels |\n\n### Retention\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /retention | Query Retention Report |\n| GET | /retention/addiction | Query Frequency Report |\n\n### Segmentation\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /segmentation | Query Segmentation Report |\n| GET | /segmentation/numeric | Numerically Bucket |\n| GET | /segmentation/sum | Numerically Sum |\n| GET | /segmentation/average | Numerically Average |\n\n### Stream\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /stream/query | Profile Event Activity |\n\n### Cohorts\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /cohorts/list | List Saved Cohorts |\n\n### Engage\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /engage | Query Profiles |\n\n### Events\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /events | Aggregate Event Counts |\n| GET | /events/top | Today's Top Events |\n| GET | /events/names | Top Events |\n| GET | /events/properties | Aggregrated Event Property Values |\n| GET | /events/properties/top | Top Event Properties |\n| GET | /events/properties/values | Top Event Property Values |\n\n### Jql\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /jql | Custom JQL Query |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"List all insights?\" -> GET /insights\n- \"List all funnels?\" -> GET /funnels\n- \"List all list?\" -> GET /funnels/list\n- \"List all retention?\" -> GET /retention\n- \"List all addiction?\" -> GET /retention/addiction\n- \"List all segmentation?\" -> GET /segmentation\n- \"List all numeric?\" -> GET /segmentation/numeric\n- \"List all sum?\" -> GET /segmentation/sum\n- \"List all average?\" -> GET /segmentation/average\n- \"List all query?\" -> GET /stream/query\n- \"Create a list?\" -> POST /cohorts/list\n- \"Create a engage?\" -> POST /engage\n- \"List all events?\" -> GET /events\n- \"List all top?\" -> GET /events/top\n- \"List all names?\" -> GET /events/names\n- \"List all properties?\" -> GET /events/properties\n- \"List all values?\" -> GET /events/properties/values\n- \"Create a jql?\" -> POST /jql\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Query API\n@base https://mixpanel.com/api/query\n@version 1.0.0\n@common_fields {workspace_id: int # The id of the workspace if applicable.}\n@endpoints 19\n@toc insights(1), funnels(2), retention(2), segmentation(4), stream(1), cohorts(1), engage(1), events(6), jql(1)\n\n@group insights\n@endpoint GET /insights\n@desc Query Saved Report\n@required {bookmark_id: int # The ID of your Insights report can be found from the url: `https://mixpanel.com/project//view//app/boards#id=12345&editor-card-id=%22report-%22`}\n@returns(200) {computed_at: str, date_range: map{from_date: str, to_date: str}, headers: [str], series: map} # Success\n\n@endgroup\n\n@group funnels\n@endpoint GET /funnels\n@desc Query Saved Report\n@required {funnel_id: int # The funnel that you wish to get data for.}\n@optional {length: int # The number of units (defined by length_unit) each user has to complete the funnel, starting from the time they triggered the first step in the funnel. May not be greater than 90 days. Note that we will query for events past the end of to_date to look for funnel completions. This defaults to the value that was previously saved in the UI for this funnel., length_unit: str(day/hour/minute/second), interval: int # The number of days you want each bucket to contain. The default value is 1., unit: str(day/week/month) # This is an alternate way of specifying interval and can be \"day\", \"week\", or \"month\"., on: str # The property expression to segment the event on. See the [expression to segment](ref:segmentation-expressions) below., where: str # An expression to filter events by. See the [expression to segment](ref:segmentation-expressions) below., limit: int # Return the top property values. Defaults to 255 if not explicitly included. Maximum value 10,000. This parameter does nothing if \\\"on\\\" is not specified.}\n@returns(200) {meta: map{dates: [str]}, data: map} # Success\n\n@endpoint GET /funnels/list\n@desc List Saved Funnels\n@returns(200) Success.\n\n@endgroup\n\n@group retention\n@endpoint GET /retention\n@desc Query Retention Report\n@optional {retention_type: str(birth/compounded) # Must be either \"birth\" or \"compounded\". Defaults to \"birth\". The “birth” retention type corresponds to first time retention. The “compounded” retention type corresponds to recurring retention. See the [Types of Retention](https://help.mixpanel.com/hc/en-us/articles/360001370146) article for more information., born_event: str # The first event a user must do to be counted in a birth retention cohort. Required when retention_type is \"birth\"; ignored otherwise., event: str # The event to generate returning counts for. Applies to both birth and compounded retention. If not specified, we look across all events., born_where: str # An expression to filter born_events by. See the [expressions section](ref:segmentation-expressions) above., where: str # An expression to filter born_events by. See the [expressions section](ref:segmentation-expressions) above., interval: int # The number of units (can be specified in either days, weeks, or months) that you want per individual bucketed interval. May not be greater than 90 days if days is the specified unit. The default value is 1., interval_count: int # The number of individual buckets, or intervals, that are returned; defaults to 1. Note that we include a \"0th\" interval for events that take place less than one interval after the initial event., unit: str(day/week/month) # The interval unit. It can be \"day\", \"week\", or \"month\". Default is \"day\"., unbounded_retention: bool=false # A counting method for retention queries where retention values accumulate from right to left, i.e. day N is equal to users who retained on day N and any day after. The default value of false does not perform this accumulation. [Learn more about Counting Method](https://help.mixpanel.com/hc/en-us/articles/360045484191)., on: str # The property expression to segment the second event on. See the [expressions section](ref:segmentation-expressions) above., limit: int # Return the top limit segmentation values. This parameter does nothing if \"on\" is not specified.}\n@returns(200) Success.\n\n@endpoint GET /retention/addiction\n@desc Query Frequency Report\n@required {unit: str(day/week/month) # The overall time period to return frequency of actions for can be \"day\", \"week\", or \"month\"., addiction_unit: str(hour/day) # The granularity to return frequency of actions at can be \"hour\" or \"day\".}\n@optional {event: str # The event to generate returning counts for., where: str # An expression to filter the returning events by. See the [expressions section](ref:segmentation-expressions) above., on: str # The property expression to segment the second event on. See the [expressions section](ref:segmentation-expressions) above., limit: int # Return the top limit segmentation values. This parameter does nothing if \"on\" is not specified.}\n@returns(200) {data: map} # Success.\n\n@endgroup\n\n@group segmentation\n@endpoint GET /segmentation\n@desc Query Segmentation Report\n@required {event: str # The event that you wish to get data for. Note: this is a single event name, not an array.}\n@optional {on: str # The property expression to segment the event on. See the [expression to segment](ref:segmentation-expressions) below., unit: str(minute/hour/day/month) # This can be \"minute\", \"hour\", \"day\", or \"month\". This determines the buckets into which the property values that you segment on are placed. The default value is \"day\"., interval: int # Optional parameter in lieu of 'unit' when 'type' is not 'general'. Determines the number of days your results are bucketed into can be used with or without 'from_date' and 'to_date' parameters., where: str # An expression to filter events by. See the [expression to segment](ref:segmentation-expressions) below., limit: int # Return the top property values. Defaults to 60. Maximum value 10,000. This parameter does nothing if \"on\" is not specified., type: str(general/unique/average) # This can be \"general\", \"unique\", or \"average\". If this is set to \"unique\", we return the unique count of events or property values. If set to \"general\", we return the total, including repeats. If set to \"average\", we return the average count. The default value is \"general\"., format: str}\n@returns(200) {data: map{series: [str], values: map}, legend_size: int} # Success.\n\n@endpoint GET /segmentation/numeric\n@desc Numerically Bucket\n@required {event: str # The event that you wish to get data for. Note: this is a single event name, not an array., on: str # The property expression to segment the event on. This expression must be a numeric property. See the [expressions section](ref:segmentation-expressions) below.}\n@optional {unit: str(hour/day) # 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\"., where: str # An expression to filter events by. See the [expression to segment](ref:segmentation-expressions) below., type: str(general/unique/average) # 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\".}\n@returns(200) {data: map{series: [str], values: map}, legend_size: int} # Success\n\n@endpoint GET /segmentation/sum\n@desc Numerically Sum\n@required {event: str # The event that you wish to get data for. Note: this is a single event name, not an array., on: str # The expression to sum per unit time. The result of the expression should be a numeric value. If the expression is not numeric, a value of 0.0 is assumed. See the [expressions section](ref:segmentation-expressions) below.}\n@optional {unit: str(hour/day) # 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\"., where: str # An expression to filter events by. See the [expression to segment](ref:segmentation-expressions) below.}\n@returns(200) {status: str, computed_at: str, results: map} # Success.\n\n@endpoint GET /segmentation/average\n@desc Numerically Average\n@required {event: str # The event that you wish to get data for. Note: this is a single event name, not an array., on: str # The expression to sum per unit time. The result of the expression should be a numeric value. If the expression is not numeric, a value of 0.0 is assumed. See the [expressions section](ref:segmentation-expressions) below.}\n@optional {unit: str(hour/day) # 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\"., where: str # An expression to filter events by. See the [expression to segment](ref:segmentation-expressions) below.}\n@returns(200) {results: map, status: str} # Success\n\n@endgroup\n\n@group stream\n@endpoint GET /stream/query\n@desc Profile Event Activity\n@required {distinct_ids: str # A JSON array as a string representing the `distinct_ids` to return activity feeds for. For example: `[\"12a34aa567eb8d-9ab1c26f345b67-89123c45-6aeaa7-89f12af345f678\"]`}\n@returns(200) {status: str, results: map{events: [map]}} # Success.\n\n@endgroup\n\n@group cohorts\n@endpoint POST /cohorts/list\n@desc List Saved Cohorts\n@returns(200) Success.\n\n@endgroup\n\n@group engage\n@endpoint POST /engage\n@desc Query Profiles\n@returns(200) {page: int, page_size: int, session_id: str, status: str, total: int, results: [map]} # Success.\n\n@endgroup\n\n@group events\n@endpoint GET /events\n@desc Aggregate Event Counts\n@required {event: str # The event or events that you wish to get data for, encoded as a JSON array. Example format: \"[\"play song\", \"log in\", \"add playlist\"]\"., type: str(general/unique/average) # The analysis type you would like to get data for - such as general, unique, or average events. Valid values: \"general\", \"unique\", or \"average\"., unit: str(minute/hour/day/week/month) # This can be \"minute\", \"hour\", \"day\", \"week\", or \"month\". It determines the level of granularity of the data you get back. Note that you cannot get hourly uniques.}\n@optional {interval: int # The number of \"units\" to return data for - minutes, hours, days, weeks, or months. 1 will return data for the current unit (minute, hour, day, week or month). 2 will return the current and previous units, and so on. Specify either interval or from_date and to_date., format: str(json/csv) # The data return format, such as JSON or CSV. Options: \"json\" (default), \"csv\".}\n@returns(200) {data: map{series: [str], values: map}, legend_size: int} # Success.\n\n@endpoint GET /events/top\n@desc Today's Top Events\n@required {type: str(general/unique/average) # The analysis type you would like to get data for - such as general, unique, or average events. Valid values: \"general\", \"unique\", or \"average\".}\n@optional {limit: int # The maximum number of events to return. Defaults to 100.}\n@returns(200) {events: [map], type: str} # Success.\n\n@endpoint GET /events/names\n@desc Top Events\n@required {type: str(general/unique/average) # The analysis type you would like to get data for - such as general, unique, or average events. Valid values: \"general\", \"unique\", or \"average\".}\n@optional {limit: int # The maximum number of values to return. Defaults to 255.}\n@returns(200) Success.\n\n@endpoint GET /events/properties\n@desc Aggregrated Event Property Values\n@required {event: str # The event that you wish to get data for. Note: this is a single event name, not an array., name: str # The name of the property you would like to get data for., type: str(general/unique/average) # The analysis type you would like to get data for - such as general, unique, or average events. Valid values: \"general\", \"unique\", or \"average\"., unit: str(minute/hour/day/week/month) # This can be \"minute\", \"hour\", \"day\", \"week\", or \"month\". It determines the level of granularity of the data you get back. Note that you cannot get hourly uniques.}\n@optional {values: [str] # The specific property values that you would like to get data for, encoded as a JSON array. Example: If you have a property \"gender\" you may have values \"male\", \"female\" and \"unknown\". If you just want data for female and unknown users, you can include a values property that looks like \"[\"female\", \"unknown\"]\"., interval: int # The number of \"units\" to return data for - minutes, hours, days, weeks, or months. 1 will return data for the current unit (minute, hour, day, week or month). 2 will return the current and previous units, and so on. Specify either interval or from_date and to_date., format: str(json/csv) # The data return format, such as JSON or CSV. Options: \"json\" (default), \"csv\"., limit: int # The maximum number of values to return. Defaults to 255.}\n@returns(200) {data: map{series: [str], values: map}, legend_size: int} # Success.\n\n@endpoint GET /events/properties/top\n@desc Top Event Properties\n@required {event: str # The event that you wish to get data for. Note: this is a single event name, not an array.}\n@optional {limit: int # The maximum number of properties to return. Defaults to 10.}\n@returns(200) Success.\n\n@endpoint GET /events/properties/values\n@desc Top Event Property Values\n@required {event: str # The event that you wish to get data for. Note: this is a single event name, not an array., name: str # The name of the property you would like to get data for.}\n@optional {limit: int # The maximum number of values to return. Defaults to 255.}\n@returns(200) Success\n\n@endgroup\n\n@group jql\n@endpoint POST /jql\n@desc Custom JQL Query\n@returns(200) Success\n\n@endgroup\n\n@end\n"}}