aggregate.mdx

title	Aggregate Data
description	Execute MongoDB aggregation pipelines on your collection.

POST /api/data/:collectionName/aggregate

Runs a MongoDB aggregation pipeline on the specified collection. This allows for complex data processing, grouping, and transformations.

Required header

x-api-key: your pk_live_… or sk_live_… key.

Path parameters

The name of the collection to aggregate.

Query parameters

If `true`, includes soft-deleted documents (where `isDeleted: true`) in the aggregation. Defaults to `false`.

Request body

An array of aggregation stages following the standard MongoDB aggregation pipeline syntax. For security reasons, certain stages like `$out` and `$merge` are blocked.

RLS behavior

If Row-Level Security (RLS) is enabled, your backend automatically injects a $match stage at the beginning of your pipeline (or after $geoNear / $search if present). This ensures users only aggregate data they have access to.

Response fields

`true` when the aggregation was executed successfully. The results of the aggregation pipeline. Human-readable status message.

Code examples

const res = await fetch(
  'https://api.urbackend.in/api/data/orders/aggregate',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'pk_live_YOUR_KEY'
    },
    body: JSON.stringify({
      pipeline: [
        { $match: { status: 'completed' } },
        { $group: { _id: '$customerId', totalAmount: { $sum: '$amount' } } },
        { $sort: { totalAmount: -1 } }
      ]
    })
  }
);

const { success, data } = await res.json();

curl -X POST "https://api.urbackend.in/api/data/orders/aggregate?include_deleted=false" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -d '{
    "pipeline": [
      { "$group": { "_id": "$category", "count": { "$sum": 1 } } }
    ]
  }'

Success response

{
  "success": true,
  "data": [
    { "_id": "electronics", "count": 42 },
    { "_id": "books", "count": 12 }
  ],
  "message": "Aggregation executed successfully."
}

Errors

Status	Cause
400 Bad Request	Invalid pipeline syntax or blocked stage used
401 Unauthorized	Missing or invalid API key
404 Not Found	Collection does not exist