Aggregate Objects

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "group_by": [
    {
      "field": "<string>",
      "alias": "category",
      "date_trunc": "day",
      "date_part": "hour"
    }
  ],
  "aggregations": [
    {
      "function": "count",
      "alias": "<string>",
      "field": "metadata.views",
      "distinct_field": "metadata.user_id"
    }
  ],
  "filters": {
    "metadata.status": "active"
  },
  "having": [
    {
      "field": "<string>",
      "operator": "<string>",
      "value": 100
    }
  ],
  "unwind": "blobs",
  "range_buckets": [
    {
      "field": "<string>",
      "boundaries": [
        123
      ],
      "default_bucket": "other"
    }
  ],
  "sort_by": "total_count",
  "sort_direction": "desc",
  "limit": 10
}
'

{
  "results": [
    {
      "group": {},
      "metrics": {}
    }
  ],
  "total_groups": 123,
  "query_info": {}
}

Objects

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.

POST

buckets

{bucket_identifier}

objects

aggregate

Aggregate Objects

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "group_by": [
    {
      "field": "<string>",
      "alias": "category",
      "date_trunc": "day",
      "date_part": "hour"
    }
  ],
  "aggregations": [
    {
      "function": "count",
      "alias": "<string>",
      "field": "metadata.views",
      "distinct_field": "metadata.user_id"
    }
  ],
  "filters": {
    "metadata.status": "active"
  },
  "having": [
    {
      "field": "<string>",
      "operator": "<string>",
      "value": 100
    }
  ],
  "unwind": "blobs",
  "range_buckets": [
    {
      "field": "<string>",
      "boundaries": [
        123
      ],
      "default_bucket": "other"
    }
  ],
  "sort_by": "total_count",
  "sort_direction": "desc",
  "limit": 10
}
'

{
  "results": [
    {
      "group": {},
      "metrics": {}
    }
  ],
  "total_groups": 123,
  "query_info": {}
}

Headers

Authorization

string

required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Path Parameters

bucket_identifier

string

required

The unique identifier of the bucket.

Body

application/json

Aggregation configuration specifying grouping, metrics, and filters.

group_by

GroupByField · object[]

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.

Minimum array length: 1

Show child attributes

group_by.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.

group_by.alias

string | null

Optional alias for the grouped field in results. If not provided, uses the field name. Useful for nested fields to create simpler result names.

Example:

"category"

group_by.date_trunc

enum<string> | null

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.

Available options:

year,

month,

week,

day,

hour,

minute,

second

Example:

"day"

group_by.date_part

enum<string> | null

Extract specific part from date field. OPTIONAL for analyzing date patterns. Only valid for date/datetime fields. Cannot be used with date_trunc.

Available options:

year,

month,

week,

day,

dayOfWeek,

dayOfYear,

hour,

minute,

second

Example:

"hour"

aggregations

AggregationOperation · object[]

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.).

Minimum array length: 1

Show child attributes

aggregations.function

enum<string>

required

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.

Available options:

count,

count_distinct,

sum,

avg,

min,

max,

first,

last,

push,

add_to_set

aggregations.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.

aggregations.field

string | null

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.

Example:

"metadata.views"

aggregations.distinct_field

string | null

Field to count distinct values from. REQUIRED when function is COUNT_DISTINCT. NOT REQUIRED for other functions. Supports dot notation for nested fields.

Example:

"metadata.user_id"

filters

Filters · object

Pre-aggregation filters to apply to source data. OPTIONAL, filters data before grouping. Uses same syntax as standard query filters. Applied before GROUP BY.

Example:

{ "metadata.status": "active" }

having

HavingCondition · object[] | null

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.

Show child attributes

having.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.

having.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).

having.value

required

Value to compare against. REQUIRED, type should match aggregation result type. Numeric for COUNT/SUM/AVG, string for grouped values.

Example:

100

unwind

string | null

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.

Example:

"blobs"

range_buckets

RangeBucket · object[] | null

Range-based bucketing for numeric fields. OPTIONAL, creates histogram-style buckets. Groups numeric values into defined ranges. Applied during grouping stage.

Show child attributes

range_buckets.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.

range_buckets.boundaries

(integer | number)[]

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.

Minimum array length: 1

range_buckets.default_bucket

string | null

Name for values outside defined boundaries. OPTIONAL, defaults to 'other'. Used for values below min or above max boundary.

Example:

"other"

sort_by

string | null

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.

Example:

"total_count"

sort_direction

string

default:desc

Sort direction. OPTIONAL, defaults to 'desc' (descending). Valid values: 'asc' (ascending), 'desc' (descending). Used with sort_by field.

limit

integer | null

Maximum number of results to return. OPTIONAL, no limit if not specified. Applied after sorting. Useful for 'top N' queries.

Required range: x > 0

Example:

10

Response

Successful Response

Response containing object aggregation results.

Returns aggregated statistics grouped by specified fields.

results

AggregationResult · object[]

required

List of aggregation results, one per group.

Show child attributes

results.group

Group · object

required

Grouped field values that define this result row.

results.metrics

Metrics · object

required

Computed aggregation values for this group.

total_groups

integer

required

Total number of unique groups returned.

query_info

Query Info · object

Additional information about the query execution. May include pipeline stages, execution time, etc.

List Objects Delete Object

⌘I

Health

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

Aggregate Objects

Headers

Path Parameters

Body

Response