> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Aggregate Objects > This endpoint performs aggregation operations on objects in a bucket. **Aggregation Framework**: Provides MongoDB-style aggregation operations: - GROUP BY: Group objects by one or more fields - Aggregations: COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT, etc. - Date Operations: Truncate or extract date parts for time-series analysis - Filtering: Pre-aggregation filters (WHERE) and post-aggregation filters (HAVING) - Sorting & Limiting: Control result ordering and size **Use Cases**: - Count objects by status or category - Calculate daily/monthly upload statistics - Analyze content distribution and trends - Generate reports with multiple metrics **Note**: This endpoint works with both MongoDB objects and Qdrant documents using the same interface. The system automatically selects the appropriate aggregation provider. ## OpenAPI ````yaml post /v1/buckets/{bucket_identifier}/objects/aggregate openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/buckets/{bucket_identifier}/objects/aggregate: post: tags: - Bucket Objects summary: Aggregate Objects description: |- This endpoint performs aggregation operations on objects in a bucket. **Aggregation Framework**: Provides MongoDB-style aggregation operations: - GROUP BY: Group objects by one or more fields - Aggregations: COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT, etc. - Date Operations: Truncate or extract date parts for time-series analysis - Filtering: Pre-aggregation filters (WHERE) and post-aggregation filters (HAVING) - Sorting & Limiting: Control result ordering and size **Use Cases**: - Count objects by status or category - Calculate daily/monthly upload statistics - Analyze content distribution and trends - Generate reports with multiple metrics **Note**: This endpoint works with both MongoDB objects and Qdrant documents using the same interface. The system automatically selects the appropriate aggregation provider. operationId: aggregate_objects_v1_buckets__bucket_identifier__objects_aggregate_post parameters: - name: bucket_identifier in: path required: true schema: type: string description: The unique identifier of the bucket. title: Bucket Identifier description: The unique identifier of the bucket. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ObjectAggregationRequest' description: >- Aggregation configuration specifying grouping, metrics, and filters. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ObjectAggregationResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ObjectAggregationRequest: properties: group_by: items: $ref: '#/components/schemas/GroupByField' type: array minItems: 1 title: Group By description: >- Fields to group results by. REQUIRED, at least one field. Can include field transformations (date_trunc, date_part). Results will have one row per unique combination of group_by values. aggregations: items: $ref: '#/components/schemas/AggregationOperation' type: array minItems: 1 title: Aggregations description: >- Aggregation operations to perform. REQUIRED, at least one operation. Each operation produces a calculated field in results. Can combine multiple functions (COUNT, SUM, AVG, etc.). filters: anyOf: - additionalProperties: true type: object - type: 'null' title: Filters description: >- Pre-aggregation filters to apply to source data. OPTIONAL, filters data before grouping. Uses same syntax as standard query filters. Applied before GROUP BY. examples: - metadata.status: active - created_at: $gte: '2024-01-01' metadata.type: video having: anyOf: - items: $ref: '#/components/schemas/HavingCondition' type: array - type: 'null' title: Having description: >- Post-aggregation filters to apply to results. OPTIONAL, filters groups after aggregation. Uses aggregation aliases as field names. Applied after GROUP BY and aggregation calculations. unwind: anyOf: - type: string - type: 'null' title: Unwind description: >- Array field to unwind before aggregation. OPTIONAL, creates one document per array element. Useful for aggregating over array contents. Example: 'blobs' to analyze each blob separately. examples: - blobs - metadata.tags - metadata.categories range_buckets: anyOf: - items: $ref: '#/components/schemas/RangeBucket' type: array - type: 'null' title: Range Buckets description: >- Range-based bucketing for numeric fields. OPTIONAL, creates histogram-style buckets. Groups numeric values into defined ranges. Applied during grouping stage. sort_by: anyOf: - type: string - type: 'null' title: Sort By description: >- Field to sort results by. OPTIONAL, can be group_by field or aggregation alias. Defaults to no specific order. Use with sort_direction to control order. examples: - total_count - avg_duration - category sort_direction: type: string title: Sort Direction description: >- Sort direction. OPTIONAL, defaults to 'desc' (descending). Valid values: 'asc' (ascending), 'desc' (descending). Used with sort_by field. default: desc examples: - asc - desc limit: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Limit description: >- Maximum number of results to return. OPTIONAL, no limit if not specified. Applied after sorting. Useful for 'top N' queries. examples: - 10 - 50 - 100 type: object required: - group_by - aggregations title: ObjectAggregationRequest description: |- Aggregation request for bucket objects. Extends the base AggregationRequest with object-specific context. Inherits all fields from AggregationRequest. Requirements: - group_by: REQUIRED, fields to group by - aggregations: REQUIRED, aggregation operations to perform - All other fields from AggregationRequest are available Examples: - Count objects by status - Daily upload statistics - Category-based analytics with filtering examples: - aggregations: - alias: total function: count description: Count objects by status group_by: - alias: status field: status sort_by: total sort_direction: desc - aggregations: - alias: uploads function: count - alias: unique_users distinct_field: metadata.user_id function: count_distinct description: Daily upload statistics group_by: - alias: date date_trunc: day field: created_at sort_by: date sort_direction: asc - aggregations: - alias: count function: count - alias: total_size field: metadata.size function: sum - alias: avg_size field: metadata.size function: avg description: Content type distribution with size stats group_by: - alias: type field: content_type having: - field: count operator: gte value: 5 sort_by: total_size sort_direction: desc ObjectAggregationResponse: properties: results: items: $ref: '#/components/schemas/AggregationResult' type: array title: Results description: List of aggregation results, one per group. total_groups: type: integer title: Total Groups description: Total number of unique groups returned. query_info: additionalProperties: true type: object title: Query Info description: >- Additional information about the query execution. May include pipeline stages, execution time, etc. type: object required: - results - total_groups title: ObjectAggregationResponse description: |- Response containing object aggregation results. Returns aggregated statistics grouped by specified fields. examples: - query_info: execution_time_ms: 45 pipeline_stages: 5 results: - group: status: completed metrics: total: 1523 - group: status: pending metrics: total: 87 total_groups: 2 ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError GroupByField: properties: field: type: string title: Field description: >- The field path to group by. Supports dot notation for nested fields (e.g., 'metadata.category'). For date fields, can be combined with date_trunc or date_part. examples: - metadata.category - status - created_at - metadata.user_id alias: anyOf: - type: string - type: 'null' title: Alias description: >- Optional alias for the grouped field in results. If not provided, uses the field name. Useful for nested fields to create simpler result names. examples: - category - upload_date - user date_trunc: anyOf: - $ref: '#/components/schemas/DateTruncUnit' - type: 'null' description: >- Truncate date field to specified unit. REQUIRED when grouping by date/time periods. Only valid for date/datetime fields. Cannot be used with date_part. examples: - day - month - hour date_part: anyOf: - $ref: '#/components/schemas/DatePartUnit' - type: 'null' description: >- Extract specific part from date field. OPTIONAL for analyzing date patterns. Only valid for date/datetime fields. Cannot be used with date_trunc. examples: - hour - dayOfWeek - month type: object required: - field title: GroupByField description: >- Configuration for grouping by a field. Defines how to group data by a specific field, with optional transformations. Requirements: - field: REQUIRED, the field to group by - alias: OPTIONAL, name for the grouped field in results - date_trunc: OPTIONAL, truncate date fields to time periods - date_part: OPTIONAL, extract part of date field Examples: - Simple grouping: GroupByField(field="metadata.category") - Daily grouping: GroupByField(field="created_at", date_trunc=DateTruncUnit.DAY) - Hour of day: GroupByField(field="created_at", date_part=DatePartUnit.HOUR) examples: - alias: category description: Group by category field: metadata.category - alias: date date_trunc: day description: Group by day field: created_at - alias: hour date_part: hour description: Group by hour of day field: created_at AggregationOperation: properties: function: $ref: '#/components/schemas/AggregationFunction' description: >- The aggregation function to apply. Different functions require different field types: COUNT: no field required. SUM/AVG: numeric fields only. MIN/MAX: numeric or date fields. COUNT_DISTINCT: any field type. field: anyOf: - type: string - type: 'null' title: Field description: >- The field to aggregate. REQUIRED for all functions except COUNT. NOT REQUIRED for COUNT (counts documents). Supports dot notation for nested fields. Field type must be compatible with function. examples: - metadata.views - metadata.duration - blobs.size - created_at alias: type: string title: Alias description: >- Name for the aggregation result in output. REQUIRED for all operations. Should be descriptive of the calculation. Used to reference results in post-filtering. examples: - total_count - total_views - avg_duration - max_size distinct_field: anyOf: - type: string - type: 'null' title: Distinct Field description: >- Field to count distinct values from. REQUIRED when function is COUNT_DISTINCT. NOT REQUIRED for other functions. Supports dot notation for nested fields. examples: - metadata.user_id - metadata.ip_address - object_id type: object required: - function - alias title: AggregationOperation description: |- Configuration for an aggregation operation. Defines a calculation to perform on grouped data. Requirements: - function: REQUIRED, the aggregation function to apply - field: REQUIRED for most functions (except COUNT), field to aggregate - alias: REQUIRED, name for the result in output Examples: - Count: AggregationOperation(function="count", alias="total_count") - Sum: AggregationOperation(function="sum", field="metadata.views", alias="total_views") - Average: AggregationOperation(function="avg", field="metadata.duration", alias="avg_duration") examples: - alias: total_count description: Count total documents function: count - alias: total_views description: Sum all views field: metadata.views function: sum - alias: avg_duration description: Average duration field: metadata.duration function: avg - alias: unique_users description: Count unique users distinct_field: metadata.user_id function: count_distinct HavingCondition: properties: field: type: string title: Field description: >- The aggregated field to filter on. REQUIRED, must match an aggregation operation alias. Used after aggregation to filter groups. Not a source field, but a computed field. examples: - total_count - avg_duration - total_views operator: type: string title: Operator description: >- Comparison operator. REQUIRED, valid operators: gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal), eq (equal), ne (not equal). examples: - gt - gte - lt - lte - eq - ne value: anyOf: - type: integer - type: number - type: string title: Value description: >- Value to compare against. REQUIRED, type should match aggregation result type. Numeric for COUNT/SUM/AVG, string for grouped values. examples: - 100 - 60 - active type: object required: - field - operator - value title: HavingCondition description: |- Filtering condition for aggregated results. Filters groups after aggregation (like SQL HAVING clause). Requirements: - field: REQUIRED, the aggregation alias to filter on - operator: REQUIRED, comparison operator - value: REQUIRED, value to compare against Examples: - Keep high-count groups: HavingCondition(field="total_count", operator="gt", value=100) - Filter by average: HavingCondition(field="avg_duration", operator="gte", value=60) examples: - description: Groups with more than 100 items field: total_count operator: gt value: 100 - description: Average duration at least 60 seconds field: avg_duration operator: gte value: 60 RangeBucket: properties: field: type: string title: Field description: >- Numeric field to create buckets for. REQUIRED, must be a numeric field. Supports dot notation for nested fields. Values will be grouped into ranges defined by boundaries. examples: - metadata.duration - metadata.views - metadata.file_size boundaries: items: anyOf: - type: integer - type: number type: array minItems: 1 title: Boundaries description: >- List of boundary values defining bucket ranges. REQUIRED, must be sorted in ascending order. Creates N+1 buckets for N boundaries: [0, 10, 20] creates: <0, 0-10, 10-20, >20. Values on boundaries go into the lower bucket. examples: - - 0 - 60 - 300 - 600 - - 0 - 100 - 1000 - 10000 default_bucket: anyOf: - type: string - type: 'null' title: Default Bucket description: >- Name for values outside defined boundaries. OPTIONAL, defaults to 'other'. Used for values below min or above max boundary. examples: - other - outliers - unknown type: object required: - field - boundaries title: RangeBucket description: |- Configuration for range-based bucketing. Groups numeric values into ranges/buckets for histogram-style analysis. Requirements: - field: REQUIRED, numeric field to bucket - boundaries: REQUIRED, list of boundary values defining buckets - default_bucket: OPTIONAL, name for values outside boundaries Examples: - Video duration buckets: [0, 60, 300, 600] creates: 0-60s, 60-300s, 300-600s, 600+s - View count buckets: [0, 100, 1000, 10000] creates: 0-100, 100-1K, 1K-10K, 10K+ views examples: - boundaries: - 0 - 60 - 300 - 600 default_bucket: over_600s description: Duration buckets (0-60s, 60-300s, 300-600s, 600+s) field: metadata.duration - boundaries: - 0 - 100 - 1000 - 10000 default_bucket: viral description: View count buckets field: metadata.views AggregationResult: properties: group: additionalProperties: true type: object title: Group description: Grouped field values that define this result row. metrics: additionalProperties: true type: object title: Metrics description: Computed aggregation values for this group. type: object required: - group - metrics title: AggregationResult description: |- Single aggregation result row. Contains grouped field values and computed aggregations. examples: - group: category: sports metrics: avg_duration: 245.3 total_count: 1523 ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError DateTruncUnit: type: string enum: - year - month - week - day - hour - minute - second title: DateTruncUnit description: |- Date truncation units for time-based grouping. Used to group data by time periods. Values: YEAR: Group by year MONTH: Group by month WEEK: Group by week DAY: Group by day HOUR: Group by hour MINUTE: Group by minute SECOND: Group by second Examples: - Use DAY to group video uploads by day - Use MONTH to analyze monthly trends DatePartUnit: type: string enum: - year - month - week - day - dayOfWeek - dayOfYear - hour - minute - second title: DatePartUnit description: |- Date part extraction units. Used to extract specific components from dates for grouping. Values: YEAR: Extract year (2024) MONTH: Extract month (1-12) WEEK: Extract week of year (1-53) DAY: Extract day of month (1-31) DAY_OF_WEEK: Extract day of week (1=Sunday, 7=Saturday) DAY_OF_YEAR: Extract day of year (1-366) HOUR: Extract hour (0-23) MINUTE: Extract minute (0-59) SECOND: Extract second (0-59) Examples: - Use DAY_OF_WEEK to analyze weekly patterns - Use HOUR to find peak usage times AggregationFunction: type: string enum: - count - count_distinct - sum - avg - min - max - first - last - push - add_to_set title: AggregationFunction description: |- Supported aggregation functions. These functions can be applied to fields during aggregation operations. Values: COUNT: Count total number of items in each group COUNT_DISTINCT: Count unique values in a field SUM: Sum numeric values AVG: Calculate average of numeric values MIN: Find minimum value MAX: Find maximum value FIRST: Get first value in group LAST: Get last value in group PUSH: Collect all values into an array ADD_TO_SET: Collect unique values into an array Examples: - Use COUNT for total items per category - Use COUNT_DISTINCT for unique users per day - Use SUM for total revenue - Use AVG for average video duration ````