Skip to main content
POST
/
models
/
instances
/
aggregate
Python SDK
from cognite.client.data_classes.data_modeling import ViewId, aggregations as aggs
avg_run_time = aggs.Avg("runTimeMinutes")
view_id = ViewId("mySpace", "PersonView", "v1")
res = client.data_modeling.instances.aggregate(view_id, avg_run_time, group_by="releaseYear")
from cognite.client.data_classes.data_modeling import aggregations as aggs, ViewId
birth_by_decade = aggs.Histogram("birthYear", interval=10.0)
view_id = ViewId("mySpace", "PersonView", "v1")
res = client.data_modeling.instances.histogram(view_id, birth_by_decade)
{
  "items": [
    {
      "instanceType": "node",
      "aggregates": [
        {
          "aggregate": "avg",
          "property": "duration",
          "value": 0.2
        }
      ],
      "group": {
        "name": "PumpName1",
        "tag": "tag01"
      }
    }
  ],
  "typing": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.cognite.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.

Body

application/json

Aggregation specification.

Defines an aggregation request. This will let you group, and aggregate supported data types. The request supports filters, and allows optional search matching.

​
view
object
required

Reference to a view

​
query
string

Optional query string. The API will parse the query string, and use it to match the text properties on elements to use for the aggregate(s).

​
properties
string[]

Optional list (array) of properties you want to apply the query above to. If you do not list any properties, you search through text fields by default.

Required array length: 1 - 200 elements
​
limit
integer
default:100

Limit the number of results returned. The default limit is currently at 100 items.

Required range: 1 <= x <= 1000
​
aggregates
(avg · object | count · object | min · object | max · object | sum · object | histogram · object)[]
Maximum array length: 5

Calculates the average from the data stored by the specified property. This aggregation uses an average mean calculation, and not an integral mean.

​
groupBy
string[]

The selection of fields to group the results by when doing aggregations. You can specify up to 5 items to group by.

When you do not specify any aggregates, the fields listed in the groupBy clause will return the unique values stored for each field. The property types supported for groupBy are text, direct, int32, int64, float32, float64, boolean, and enum.

Required array length: 1 - 5 elements
​
filter
and · object

Build a new query by combining other queries, using boolean operators. We support the and, or, and not boolean operators.

Example:
{
  "and": [
    {
      "in": {
        "property": ["tag"],
        "values": [10011, 10011]
      }
    },
    {
      "range": { "property": ["weight"], "gte": 0 }
    }
  ]
}
​
operator
enum<string>
default:OR

Controls how multiple search terms are combined when matching documents.

  • OR (default): A document matches if it contains any of the query terms in the searchable fields. This typically returns more results but with lower precision.

  • AND: A document matches only if it contains all of the query terms across the searchable fields. This typically returns fewer results but with higher relevance.

Available options:
AND,
OR
​
instanceType
enum<string>
default:node

The type of instance

Available options:
node,
edge
​
targetUnits
object[]

Properties to convert to another unit. The API can only convert to another unit, if a unit has been defined as part of the type on the underlying container being queried.

Required array length: 1 - 10 elements
​
includeTyping
boolean
default:false

Should we return property type information as part of the result?

Response

Aggregated query results

​
items
object[]
required
​
typing
object

Spaces for the requested view and containers

Last modified on June 2, 2026