---
title: "Aggregate Objects"
method: POST
path: "/v1/buckets/{bucket_identifier}/objects/aggregate"
tags: ["Bucket Objects"]
---

# Aggregate Objects

`POST /v1/buckets/{bucket_identifier}/objects/aggregate`

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.

## Path parameters

- `bucket_identifier` string, required — The unique identifier of the bucket.

## Request body

- ObjectAggregationRequest — 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
  - `group_by` GroupByField[], required — 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.
    - `field` string, required — 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.
    - `alias` string, nullable — Optional alias for the grouped field in results. If not provided, uses the field name. Useful for nested fields to create simpler result names.
    - `date_trunc` 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' — 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
    - `date_part` 'year' | 'month' | 'week' | 'day' | 'dayOfWeek' | 'dayOfYear' | 'hour' | 'minute' | 'second' — 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
  - `aggregations` AggregationOperation[], required — 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.).
    - `function` 'count' | 'count_distinct' | 'sum' | 'avg' | 'min' | 'max' | 'first' | 'last' | 'push' | 'add_to_set', required — 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
    - `field` string, nullable — 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.
    - `alias` string, required — Name for the aggregation result in output. REQUIRED for all operations. Should be descriptive of the calculation. Used to reference results in post-filtering.
    - `distinct_field` string, nullable — Field to count distinct values from. REQUIRED when function is COUNT_DISTINCT. NOT REQUIRED for other functions. Supports dot notation for nested fields.
  - `filters` object, nullable — Pre-aggregation filters to apply to source data. OPTIONAL, filters data before grouping. Uses same syntax as standard query filters. Applied before GROUP BY.
  - `having` HavingCondition[], nullable — 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.
    - `field` string, required — 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.
    - `operator` string, required — 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).
    - `value` union, required — Value to compare against. REQUIRED, type should match aggregation result type. Numeric for COUNT/SUM/AVG, string for grouped values.
      - integer
      - number
      - string
  - `unwind` string, nullable — 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.
  - `range_buckets` RangeBucket[], nullable — Range-based bucketing for numeric fields. OPTIONAL, creates histogram-style buckets. Groups numeric values into defined ranges. Applied during grouping stage.
    - `field` string, required — 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.
    - `boundaries` union[], required — 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.
      - union
        - integer
        - number
    - `default_bucket` string, nullable — Name for values outside defined boundaries. OPTIONAL, defaults to 'other'. Used for values below min or above max boundary.
  - `sort_by` string, nullable — 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.
  - `sort_direction` string — Sort direction. OPTIONAL, defaults to 'desc' (descending). Valid values: 'asc' (ascending), 'desc' (descending). Used with sort_by field.
  - `limit` integer, nullable — Maximum number of results to return. OPTIONAL, no limit if not specified. Applied after sorting. Useful for 'top N' queries.

## Response `200`

Successful Response

- ObjectAggregationResponse — Response containing object aggregation results. Returns aggregated statistics grouped by specified fields.
  - `results` AggregationResult[], required — List of aggregation results, one per group.
    - `group` object, required — Grouped field values that define this result row.
    - `metrics` object, required — Computed aggregation values for this group.
  - `total_groups` integer, required — Total number of unique groups returned.
  - `query_info` object — Additional information about the query execution. May include pipeline stages, execution time, etc.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)