Why use aggregations?

Aggregations let you ask questions about your data instead of retrieving the full list of matching documents. Typical use‑cases include:

Building dashboards – e.g. “show the average renewal amount per month”
Powering filters – e.g. “list the top 10 contract owners and the number of contracts per owner”
Quick analytics – e.g. “count deals by stage and sum their values”

At request time you attach an aggs block whose shape is described below.

High‑level schema

{
  "field": "index field to aggregate on",
  "aggregationType": "one of: metric | groupBy | date_range | date_histogram",
  "options": "type‑specific options (see below)",
  "aggs": "(optional) nested aggregation – same schema recursively"
}

Common optional helpers (allowed everywhere unless stated otherwise):

size – max number of buckets to return (default: index.max_terms, hard‑limit 100)
sort – how to order buckets. Shape varies by aggregation type.

aggregationType: metric

Use when you need a single numeric answer (sum, average, …) instead of buckets.

Field	Required?	Description
`field`	✔	Numeric field to summarise
`aggregationType`	✔	metric
`options.metricFunction`	✔	`sum`, `avg`, `max`, `min`
`options.size`	✖	Number of buckets to keep (after sorting); max 100
`options.sort`	✖	`{ field, aggFunc, order }` `field` – the field inside the bucket to sort by (usually same as parent) `aggFunc` – one of the metric functions above `order` – `min` or `max`

Example – average apps per user

{
  "field":"activeAppsCount",
  "aggregationType":"metric",
  "options":{"metricFunction":"avg"}
}

curl 'https://api.toriih.com/v1.0/users?aggs={%20%22field%22%3A%22activeAppsCount%22%2C%20%22aggregationType%22%3A%22metric%22%2C%20%22options%22%3A{%22metricFunction%22%3A%22avg%22}}' \
--header 'Authorization: Bearer <API_KEY>'

aggregationType: groupBy

Buckets documents by the exact value of field (keyword/text). Optionally compute metrics per bucket.

Field	Required?	Description
`field`	✔	Keyword or numeric field whose unique values become bucket keys
`aggregationType`	✔	groupBy
`options.size`	✖	Number of buckets to keep (after sorting); max 100
`options.sort`	✖	Same structure as metric
`options.metricFunction`	✖	`total` (document count) plus any metric functions (`sum`, `avg`, `max`, `min`) to compute inside each bucket

Example – group apps by source

{
  "field":"sources",
  "aggregationType":"groupBy",
  "options":{
    "sort":{
      "order":"desc",
      "aggFunc":"total"
    },
    "size":5
  }
}

curl 'https://api.toriih.com/v1.0/apps?aggs={%22field%22%3A%22sources%22%2C%22aggregationType%22%3A%22groupBy%22%2C%22options%22%3A{%22sort%22%3A{%22order%22%3A%22desc%22%2C%22aggFunc%22%3A%22total%22}%2C%22size%22%3A5}}' \
--header 'X-API-VERSION: 1.1' \
--header 'Authorization: Bearer <API_KEY>'

aggregationType: date_range

Splits documents into arbitrary, possibly overlapping, date ranges.

Field	Required?	Description
`field`	✔	Date field (RFC‑3339 strings)
`aggregationType`	✔	date_range
`options.size`	✖	Number of buckets to keep (after sorting); max 100
`options.sort`	✖	`{ field, order }` – same structure as metric but without `aggFunc`

aggregationType: date_histogram

Produces contiguous calendar buckets (week / month / quarter / year).

Field	Required?	Description
`field`	✔	Date field
`aggregationType`	✔	date_histogram
`options.dateHistogramOptions.datePeriod`	✔	One of `weekly`, `monthly`, `quarterly`, `yearly`
`options.dateHistogramOptions.hardBounds`	✖	`{ min, max }` – explicit min/max bounds; buckets outside are excluded
`options.dateHistogramOptions.extendedBounds`	✖	`{ min, max }` – still create empty buckets beyond data range
`options.sort`	✖	`{ field, order }`– same structure as metric but without`aggFunc`
`options.size`	✖	Number of buckets to keep (after sorting); max 100

Example – discovered apps over time

{
  "field":"creationTime",
  "aggregationType":"date_histogram",
  "options":{
    "dateHistogramOptions":{
      "datePeriod":"monthly"
		},
    "sort":{
      "field":"creationTime",
      "order":"asc"
    },
    "size":40
  }
}

curl 'https://api.toriih.com/v1.0/apps?aggs={%22field%22%3A%22creationTime%22%2C%22aggregationType%22%3A%22date_histogram%22%2C%22options%22%3A{%22dateHistogramOptions%22%3A{%22datePeriod%22%3A%22monthly%22}%2C%22sort%22%3A{%22field%22%3A%22creationTime%22%2C%22order%22%3A%22asc%22}%2C%22size%22%3A40}}' \
--header 'X-API-VERSION: 1.1' \
--header 'Authorization: Bearer <API_KEY>'

Sorting syntax

sort {
  field    string   			// bucket key or doc field to sort by
  order   "asc" | "desc" 	// (ascending / descending)
  aggFunc  enum    				// extra metric used for ordering (metric & groupBy only)
}

Nesting aggregations

Set aggs to another aggregation object to drill down. There is no hard depth limit, but response size grows with every level, so keep it reasonable.

Example – app spend by category

{
  "field":"category",
  "aggregationType":"groupBy",
  "options":{
    "sort":{
      "field":"expenses",
      "order":"desc",
      "aggFunc":"sum"
    },
    "size":5
  },
  "aggs":{
    "field":"expenses",
    "aggregationType":"metric",
    "options":{
      "metricFunction":"sum"
    }
  }
}

Quick reference

metricFunction: sum, avg, max, min (+ total inside groupBy)
aggregationType: metric, groupBy, date_range, date_histogram
sort.order: asc (ascending) or desc (descending)
size hard‑limited to 100