--- title: "Run an aggregate function (e.g. average, mode) on a table's field." slug: "run-an-aggregate-function-eg-average-mode-on-a-tables-field" updated: 2026-04-02T17:37:08Z published: 2026-04-02T17:37:27Z --- > ## Documentation Index > Fetch the complete documentation index at: https://support.tulip.co/llms.txt > Use this file to discover all available pages before exploring further. # Run an aggregate function (e.g. average, mode) on a table's field. Get/tables/{tableId}/runAggregation Requires `tables:read` API scope. Attempting to run a numeric aggregate function e.g. sum on a non-numeric field type will generate a 422 error response. The only non-numeric functions are `mode` and `uniqueValues`. SecurityHTTPType basic Access to the Tulip API requires the use of [HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617) using the credentials of an active [Tulip API Token](https://support.tulip.co/docs/set-up-a-tulip-api). All requests require the `Authorization` HTTP header with the `Basic` scheme to provide API credentials unless otherwise noted. API tokens can be configured with a set of *scopes* which determine what parts of the API that specific token has access to. Security best practices dictate that API credentials be given the minimum set of capabilities required to fulfill their intended purpose. For example, an API token created for use in an integration that is only designed to use the Tables API should probably only be given the `tables:read` and `tables:write` scopes. In this way you can minimize risk in the event that API credentials are compromised. API endpoints will document what API token scopes are required to access that endpoint in their descriptions. If a request is made to an endpoint with an API token which does not have the required scopes, the response will be an authorization error. Header parametersX-Tulip-Number-Formatstring The format that Tulip should use in the response when formatting Tulip numbers. If omitted or set to `float`, Tulip will format numbers as JSON numbers. If set to `decimal`, Tulip will format numbers as strings representing the decimal representation of the number, like `"1.20"`. Tulip will only output trailing zeros when using `decimal` formatting. #### Filtering Tulip interprets JSON numbers as floating-point values, which may result in edge cases when this header's value is `decimal`. If you set this header to `decimal`, we recommend passing values for Tulip number fields as strings. Specifically, if this header is set to `decimal` and `filters` specifies a Tulip number field, that filter's `arg` will be interpreted as a decimal value. If it's passed in as a string, it must be of format `"[-]xx[.yyy]"`. If it's passed in as a JSON number, it will be parsed as a JavaScript number, and then converted to a decimal string. This may result in loss of precision, since JavaScript numbers have limited precision (roughly 15-17 digits). For example, the number `2.0000000000000002` cannot be expressed as a JavaScript number, so it will be parsed as `2`. This means that if you are trying to look up a value with `{... "functionType", "equal", "arg", 2.0000000000000002}`, Tulip will not find that value (since it will instead look for values that equal `2`). To specify filters for such numbers when this header is `decimal`, we recommend you pass them in as strings, like `"2.0000000000000002"`. #### Sorting If this header is set to `decimal` and `sortOptions` specifies a Tulip number field, that field will be ordered by value (as normal) and then by number of trailing zeros, with fewer zeros sorting earlier. For example, `1.2` will sort before `1.20`. If the header is unset or set to `float`, trailing zeros will not be taken into consideration when sorting. This discrepancy in the handling of trailing zeros can result in inconsistent ordering if `sortOptions` specifies multiple fields. For example, with records: | Id | myNumber | | --- | --- | | A | 1.20 | | B | 1.2 | Sorting by `myNumber, Id` with this header set to `decimal` will result in: ```json [ {"myNumber": "1.2", "Id": "B"}, {"myNumber": "1.20", "Id": "A"} ] ``` ... because `"1.20"` sorts before `"1.2"`. On the other hand, without this header, the result will be: ```json [ {"myNumber": 1.2, "Id": "A"}, {"myNumber": 1.2, "Id": "B"} ] ``` ... because the numbers are tied, so the secondary sorting on `Id` factors in. Note that this header only affects Tulip numbers. Other types, including Tulip integers, are unaffected. Valid values[ "decimal", "float" ]Default"float" Path parameterstableIdstringRequired The id of a Tulip Table. Pattern^[a-zA-Z0-9_]+$Exampleg56RCoZCtzv7borvp Query parametersfieldIdstringRequired The field to aggregate on. An invalid field name for the specified table will result in a 404 error. functionstringRequired Aggregate function names are case-insensitive. An invalid function type will result in a 400 error. Valid values[ "sum", "count", "avg", "min", "max", "mode", "uniqueValues" ] limitintegerRequired The maximum number of table records to evaluate. Minimum1Maximum100000Example10 sortOptions Sorting allows to define which records are considered if there are more than the specified limit. Sort priority is determined by the order or options, i.e. sort by the first option, them by the second, etc. If omitted, there is no guarantee as to which records are selected. A sortBy value that is not one of the table's field will generate a 422 error. Options for sortDir are "asc" and "desc". Example: `[{"sortBy": "superAwesomeField", "sortDir": "asc"}, {"sortBy": "lessAwesomeField", "sortDir": "desc"}]` filters An optional array of filter expressions to filter the Table records by. Each filter is an object specifying the `field` (name of a table column), `functionType` (comparison function), and `arg` (the value to compare to). For example: ```json [ {"field": "field1", "functionType": "equal", "arg": "hello"}, {"field": "field2", "functionType": "notBlank"}, {"field": "field3", "functionType": "isIn", "arg": ["a", "b", "c"]} ] ``` The field may be the name of a table column (including `id`) or one of these special values: - `_createdAt` (datetime) - `_updatedAt` (datetime) Linked record columns (table links) cannot be used as filter fields. The valid function types are: | Functions | `arg` | | --- | --- | | `equal`, `notEqual` | Single value | | `blank`, `notBlank` | None | | `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual` | Single value | | `isIn`, `notIsIn` | JSON array `field` may not be a datetime | | `contains`, `notContains`, `startsWith`, `notStartsWith`, `endsWith`, `notEndsWith` | Single value `field` must be a text column | #### Format by column type The required format of `arg` depends on the `field` column's type: | Column type | `arg` format | Example | | --- | --- | --- | | **text**, **`id`** | JSON string | `"hello"` | | **integer** | JSON number1 | `123` | | **number** | JSON number or decimal string `"[-]xx[.yyy]"` | `456.7` or `"456.7"` | | **boolean** | JSON boolean or equivalent string | `true` or `"true"` | | **datetime** | ISO 8601 string or Unix timestamp (integer seconds since epoch) | `"2024-01-15T10:30:00Z"` or `1736936400` | | **duration** | JSON number (seconds) | `300` (for 5 minutes) | | **color** | JSON object with integer fields `r`, `g`, `b` (0–255) and float field `a` (0–1) | `{"r": 255, "g": 128, "b": 0, "a": 1.0}` | | **imageUrl**, **fileUrl** | JSON string (the URL) | `"https://example.com/photo.jpg"` | | **user**, **machine**, **station** | JSON string (resource ID) | `"abc123xyz"` | 1: For `isIn` and `notIsIn` *only*, the list may contain either JSON numbers or JSON strings: `[1, "2"]`. This is supported for historical reasons and backwards compatibility. filterAggregatorstring How the filters in the `filters` parameter are combined. - `all` means that every filter must match a record in order for the record to be included. - `any` means at least one filter must match a record in order for the record to be included. Valid values[ "all", "any" ]Default"all" Responses200 The count of Tulip Table records was retrieved successfully. object resultnumber 400 The request was malformed. This could mean that headers, query parameters, or the request body was unable to be parsed or had unexpected values. object errorCodestring errorUniqueIDstring Pattern^[a-zA-Z0-9+/]+$Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y detailsstring 401 The request was made unauthorized. HTTP Basic Authorization using a Tulip API Key is required for use of the API. object errorCodestring errorUniqueIDstring Pattern^[a-zA-Z0-9+/]+$Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y detailsstring 403 The provided authentication info was rejected. The response will provide additional details. object errorCodestring errorUniqueIDstring Pattern^[a-zA-Z0-9+/]+$Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y detailsstring 404 The requested database entry was not found. object errorCodestring errorUniqueIDstring Pattern^[a-zA-Z0-9+/]+$Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y detailsstring 422 The request was syntactically sound, but could not be processed due to a logical problem. object errorCodestring errorUniqueIDstring Pattern^[a-zA-Z0-9+/]+$Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y detailsstring 500 The server encountered an unexpected error. object errorCodestring errorUniqueIDstring Pattern^[a-zA-Z0-9+/]+$Exampleaq21mSKC1rbO87TjC/4Hz2EJHd/v+jxf7MtC315vo0Y detailsstring