Aggregate Objects

curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "group_by": [
    {
      "field": "<string>",
      "alias": "category",
      "date_trunc": "day",
      "date_part": "hour"
    }
  ],
  "aggregations": [
    {
      "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
}
'

import requests

url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate"

payload = {
    "group_by": [
        {
            "field": "<string>",
            "alias": "category",
            "date_trunc": "day",
            "date_part": "hour"
        }
    ],
    "aggregations": [
        {
            "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    group_by: [{field: '<string>', alias: 'category', date_trunc: 'day', date_part: 'hour'}],
    aggregations: [
      {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
  })
};

fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'group_by' => [
        [
                'field' => '<string>',
                'alias' => 'category',
                'date_trunc' => 'day',
                'date_part' => 'hour'
        ]
    ],
    'aggregations' => [
        [
                '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate"

	payload := strings.NewReader("{\n  \"group_by\": [\n    {\n      \"field\": \"<string>\",\n      \"alias\": \"category\",\n      \"date_trunc\": \"day\",\n      \"date_part\": \"hour\"\n    }\n  ],\n  \"aggregations\": [\n    {\n      \"alias\": \"<string>\",\n      \"field\": \"metadata.views\",\n      \"distinct_field\": \"metadata.user_id\"\n    }\n  ],\n  \"filters\": {\n    \"metadata.status\": \"active\"\n  },\n  \"having\": [\n    {\n      \"field\": \"<string>\",\n      \"operator\": \"<string>\",\n      \"value\": 100\n    }\n  ],\n  \"unwind\": \"blobs\",\n  \"range_buckets\": [\n    {\n      \"field\": \"<string>\",\n      \"boundaries\": [\n        123\n      ],\n      \"default_bucket\": \"other\"\n    }\n  ],\n  \"sort_by\": \"total_count\",\n  \"sort_direction\": \"desc\",\n  \"limit\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"group_by\": [\n    {\n      \"field\": \"<string>\",\n      \"alias\": \"category\",\n      \"date_trunc\": \"day\",\n      \"date_part\": \"hour\"\n    }\n  ],\n  \"aggregations\": [\n    {\n      \"alias\": \"<string>\",\n      \"field\": \"metadata.views\",\n      \"distinct_field\": \"metadata.user_id\"\n    }\n  ],\n  \"filters\": {\n    \"metadata.status\": \"active\"\n  },\n  \"having\": [\n    {\n      \"field\": \"<string>\",\n      \"operator\": \"<string>\",\n      \"value\": 100\n    }\n  ],\n  \"unwind\": \"blobs\",\n  \"range_buckets\": [\n    {\n      \"field\": \"<string>\",\n      \"boundaries\": [\n        123\n      ],\n      \"default_bucket\": \"other\"\n    }\n  ],\n  \"sort_by\": \"total_count\",\n  \"sort_direction\": \"desc\",\n  \"limit\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"group_by\": [\n    {\n      \"field\": \"<string>\",\n      \"alias\": \"category\",\n      \"date_trunc\": \"day\",\n      \"date_part\": \"hour\"\n    }\n  ],\n  \"aggregations\": [\n    {\n      \"alias\": \"<string>\",\n      \"field\": \"metadata.views\",\n      \"distinct_field\": \"metadata.user_id\"\n    }\n  ],\n  \"filters\": {\n    \"metadata.status\": \"active\"\n  },\n  \"having\": [\n    {\n      \"field\": \"<string>\",\n      \"operator\": \"<string>\",\n      \"value\": 100\n    }\n  ],\n  \"unwind\": \"blobs\",\n  \"range_buckets\": [\n    {\n      \"field\": \"<string>\",\n      \"boundaries\": [\n        123\n      ],\n      \"default_bucket\": \"other\"\n    }\n  ],\n  \"sort_by\": \"total_count\",\n  \"sort_direction\": \"desc\",\n  \"limit\": 10\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

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: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "group_by": [
    {
      "field": "<string>",
      "alias": "category",
      "date_trunc": "day",
      "date_part": "hour"
    }
  ],
  "aggregations": [
    {
      "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
}
'

import requests

url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate"

payload = {
    "group_by": [
        {
            "field": "<string>",
            "alias": "category",
            "date_trunc": "day",
            "date_part": "hour"
        }
    ],
    "aggregations": [
        {
            "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    group_by: [{field: '<string>', alias: 'category', date_trunc: 'day', date_part: 'hour'}],
    aggregations: [
      {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
  })
};

fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'group_by' => [
        [
                'field' => '<string>',
                'alias' => 'category',
                'date_trunc' => 'day',
                'date_part' => 'hour'
        ]
    ],
    'aggregations' => [
        [
                '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate"

	payload := strings.NewReader("{\n  \"group_by\": [\n    {\n      \"field\": \"<string>\",\n      \"alias\": \"category\",\n      \"date_trunc\": \"day\",\n      \"date_part\": \"hour\"\n    }\n  ],\n  \"aggregations\": [\n    {\n      \"alias\": \"<string>\",\n      \"field\": \"metadata.views\",\n      \"distinct_field\": \"metadata.user_id\"\n    }\n  ],\n  \"filters\": {\n    \"metadata.status\": \"active\"\n  },\n  \"having\": [\n    {\n      \"field\": \"<string>\",\n      \"operator\": \"<string>\",\n      \"value\": 100\n    }\n  ],\n  \"unwind\": \"blobs\",\n  \"range_buckets\": [\n    {\n      \"field\": \"<string>\",\n      \"boundaries\": [\n        123\n      ],\n      \"default_bucket\": \"other\"\n    }\n  ],\n  \"sort_by\": \"total_count\",\n  \"sort_direction\": \"desc\",\n  \"limit\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"group_by\": [\n    {\n      \"field\": \"<string>\",\n      \"alias\": \"category\",\n      \"date_trunc\": \"day\",\n      \"date_part\": \"hour\"\n    }\n  ],\n  \"aggregations\": [\n    {\n      \"alias\": \"<string>\",\n      \"field\": \"metadata.views\",\n      \"distinct_field\": \"metadata.user_id\"\n    }\n  ],\n  \"filters\": {\n    \"metadata.status\": \"active\"\n  },\n  \"having\": [\n    {\n      \"field\": \"<string>\",\n      \"operator\": \"<string>\",\n      \"value\": 100\n    }\n  ],\n  \"unwind\": \"blobs\",\n  \"range_buckets\": [\n    {\n      \"field\": \"<string>\",\n      \"boundaries\": [\n        123\n      ],\n      \"default_bucket\": \"other\"\n    }\n  ],\n  \"sort_by\": \"total_count\",\n  \"sort_direction\": \"desc\",\n  \"limit\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/aggregate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"group_by\": [\n    {\n      \"field\": \"<string>\",\n      \"alias\": \"category\",\n      \"date_trunc\": \"day\",\n      \"date_part\": \"hour\"\n    }\n  ],\n  \"aggregations\": [\n    {\n      \"alias\": \"<string>\",\n      \"field\": \"metadata.views\",\n      \"distinct_field\": \"metadata.user_id\"\n    }\n  ],\n  \"filters\": {\n    \"metadata.status\": \"active\"\n  },\n  \"having\": [\n    {\n      \"field\": \"<string>\",\n      \"operator\": \"<string>\",\n      \"value\": 100\n    }\n  ],\n  \"unwind\": \"blobs\",\n  \"range_buckets\": [\n    {\n      \"field\": \"<string>\",\n      \"boundaries\": [\n        123\n      ],\n      \"default_bucket\": \"other\"\n    }\n  ],\n  \"sort_by\": \"total_count\",\n  \"sort_direction\": \"desc\",\n  \"limit\": 10\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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

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

filters

Filters · object | null

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

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

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.

Examples:

"asc"

"desc"

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

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

Organization

Namespaces

Buckets

Feature Extractors

Batch Queue

Collections

Documents

Retrievers

Taxonomies

Clusters

Triggers

Alerts

Webhooks

Apps

Agent Sessions

Annotations

Templates

Manifest

Discovery

Analytics

Notifications

Tasks

Inference

Resource Search

Pricing

Aggregate Objects

Authorizations

Path Parameters

Body

Response