Aggregate / statistics

post/v1/records/statistics

Computes aggregates over a filtered records root: count, sum, avg, min, max, optionally grouped by one or more fields. This is the aggregate mode of the records query engine (mode: aggregate) exposed as a dedicated endpoint. Accepts the same root + filters + whereClause as POST /v1/records/query.

Requires a bearer token: Authorization: Bearer <token>.

Request

cURL

curl -X POST https://api.wellapp.ai/v1/records/statistics \
  -H "Authorization: Bearer $WELL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "root": "invoices",
  "filters": [
    {
      "field": "status",
      "operator": "in",
      "value": [
        "issued",
        "paid"
      ],
      "conjunction": "and"
    }
  ],
  "aggregations": [
    {
      "op": "count",
      "field": "*",
      "alias": "invoice_count"
    },
    {
      "op": "sum",
      "field": "grand_total.amount",
      "alias": "total_billed"
    }
  ],
  "group_by": [
    "status"
  ]
}'

Request body

{
  "root": "invoices",
  "filters": [
    {
      "field": "status",
      "operator": "in",
      "value": [
        "issued",
        "paid"
      ],
      "conjunction": "and"
    }
  ],
  "aggregations": [
    {
      "op": "count",
      "field": "*",
      "alias": "invoice_count"
    },
    {
      "op": "sum",
      "field": "grand_total.amount",
      "alias": "total_billed"
    }
  ],
  "group_by": [
    "status"
  ]
}

Responses

200 — Aggregated results, one row per group (or a single row when group_by is empty).

{
  "data": [
    {
      "status": "issued",
      "invoice_count": 12,
      "total_billed": 48250
    },
    {
      "status": "paid",
      "invoice_count": 31,
      "total_billed": 131900
    }
  ],
  "meta": {
    "currency": "USD"
  }
}

400 — Bad Request

{
  "code": "BAD_REQUEST",
  "status": 0,
  "title": "Bad Request",
  "message": "Invalid root, field, or aggregation.",
  "meta": {
    "trace_id": "a1b2c3"
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 0,
  "title": "Unauthorized",
  "message": "Authentication required.",
  "meta": {
    "trace_id": "a1b2c3"
  }
}