Records

Aggregate records

Run a grouped aggregation query over records of a single record type - counts, sums, averages, and more, optionally grouped by up to two fields. Prefer this over paging through search and aggregating client-side. Despite the POST verb this is a read; the query travels in the body.

post/api/v2/records/aggregate

Request

  • Base URL: https://your-tenant.tines.com
  • URL: https://your-tenant.tines.com/api/v2/records/aggregate
  • Auth: one of:
    • API key in header X-User-Token
    • HTTP bearer

Request body

record_type_idinteger

Numeric record type id. Takes precedence when record_type_name is also provided.

record_type_namestring

Record type name or slug. Used when record_type_id is omitted.

aggregationsobject[] required

1-5 aggregations, each { fn, field_id? | field_name?, alias? }. fn is COUNT, SUM, AVG, MIN, MAX, or MEDIAN; all except COUNT require a NUMBER field. field_name matches a field name or slug; matching is insensitive to case and separators. alias names the output column.

group_byobject[]

0-2 groupings, each { field_id | field_name, date_trunc? }. field_name matches a field name or slug; matching is insensitive to case and separators. date_trunc (hour, day, week, month, year) applies to TIMESTAMP fields.

filterobject

Same AND-only filter tree as search (max 50 nodes). A single condition or an { op: "AND", nodes: [...] } group.

order_byobject[]

At most one { field_id | field_name | alias, direction } naming a group-by field or an aggregation alias.

parent_idsinteger[]

Restrict to records under these parents (max 100).

timezonestring

IANA timezone applied to date_trunc buckets and time-range parsing. Defaults to UTC.

limitinteger

Maximum rows to return, 1-500.

Response

Successful response

rowsobject[]

One object per result row, keyed by group-by field name and aggregation alias. Numeric aggregate values are returned as strings; COUNT is an integer.

Changes

No recorded changes to this operation across all 1 revision of this API.