> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregate Records

> Compute a sum, average, min, max, or count over a field, optionally filtered and grouped.

## Operations

| Operation        | Description                | Field requirement |
| ---------------- | -------------------------- | ----------------- |
| `sum`            | Total of all values        | Numeric field     |
| `avg`            | Average of all values      | Numeric field     |
| `min`            | Smallest value             | Any field         |
| `max`            | Largest value              | Any field         |
| `count`          | Number of non-empty values | Any field         |
| `count_distinct` | Number of distinct values  | Any field         |

<Note>
  `fieldId` (a field ID or field name) is required for every operation. `sum` and `avg` require a numeric field (`number`, `currency`, `percent`, `rating`, or `duration`).
</Note>

## Filtering

Use the optional `filter` to restrict which records are aggregated. It supports the same nested AND/OR logic as [List Records](/api/records/list-records#filtering).

## Grouping

When `groupBy` is supplied, the response returns `groupedResults` (one entry per group with its `value` and `groupValue`) instead of a single `result`.

```json theme={null}
{
  "fieldId": "Amount",
  "operation": "sum",
  "filter": { "field": "Status", "equals": "Paid" },
  "groupBy": "Region"
}
```


## OpenAPI

````yaml api/openapi.json POST /bases/{databaseId}/tables/{tableId}/records/aggregate
openapi: 3.0.1
info:
  title: Zite DB REST API
  description: >-
    A REST API for managing Zite databases, tables, fields, and records. Build
    database-driven applications with programmatic access to your structured
    data.


    ## What is REST API


    A **REST API** simplifies interaction with your database data, allowing for
    automation and integration. Following RESTful principles, it seamlessly
    connects to retrieve, create, and modify database data.


    ## Getting Started


    ### Authentication

    All API requests require authentication using your Zite API key in the
    Authorization header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    ### Base URL

    https://tables.zite.com/api/v1


    ### Rate Limits

    API requests are rate limited to ensure service quality. Standard rate
    limits apply to all endpoints.


    ### Error Handling

    The API returns standard HTTP status codes and JSON error responses with
    detailed error messages.
  version: 1.0.0
servers:
  - url: https://tables.zite.com/api/v1
    description: Zite DB API
security:
  - bearerAuth: []
tags:
  - name: Databases
    description: Operations for managing databases
  - name: Tables
    description: Operations for managing tables within databases
  - name: Fields
    description: Operations for managing fields within tables
  - name: Records
    description: Operations for managing records within tables
  - name: Webhooks
    description: >-
      Operations for managing webhook subscriptions to receive real-time
      notifications when database events occur
  - name: SQL
    description: Run read-only SQL queries against a database and inspect its SQL schema
paths:
  /bases/{databaseId}/tables/{tableId}/records/aggregate:
    post:
      tags:
        - Records
      summary: Aggregate records
      description: >-
        Computes an aggregate (sum, avg, min, max, count, or count_distinct)
        over a field, optionally filtered and grouped.
      operationId: aggregateRecords
      parameters:
        - name: databaseId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the database
        - name: tableId
          in: path
          required: true
          schema:
            type: string
          description: >-
            The unique identifier of the table. You can also use the table name
            instead of the ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregateRequest'
      responses:
        '200':
          description: Aggregation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    AggregateRequest:
      type: object
      properties:
        fieldId:
          type: string
          description: >-
            The field to aggregate, specified by field ID or field name.
            Required for all operations. `sum` and `avg` require a numeric field
            (number, currency, percent, rating, or duration).
        operation:
          type: string
          enum:
            - sum
            - avg
            - min
            - max
            - count
            - count_distinct
          description: The aggregation to perform.
        filter:
          allOf:
            - $ref: '#/components/schemas/FilterCondition'
          description: >-
            Optional filter condition restricting which records are aggregated.
            Supports the same nested AND/OR logic as List Records.
        groupBy:
          type: string
          description: >-
            Optional field (field ID or name) to group results by. When
            provided, `groupedResults` is returned instead of a single `result`.
      required:
        - fieldId
        - operation
      example:
        fieldId: Amount
        operation: sum
        filter:
          field: Status
          equals: Paid
        groupBy: Region
    AggregateResponse:
      type: object
      properties:
        fieldId:
          type: string
          description: The field ID that was aggregated.
        operation:
          type: string
          enum:
            - sum
            - avg
            - min
            - max
            - count
            - count_distinct
          description: The aggregation that was performed.
        result:
          type: number
          nullable: true
          description: >-
            The aggregated value. Null when `groupBy` is used (see
            `groupedResults`) or when no rows match. `sum` returns 0 when no
            rows match.
        groupedResults:
          type: array
          items:
            $ref: '#/components/schemas/AggregateGroupResult'
          description: Present only when `groupBy` is supplied. One entry per group.
      required:
        - fieldId
        - operation
        - result
    FilterCondition:
      type: object
      description: >-
        A filter condition that can be a single field condition or a logical
        group (and/or) of conditions. Each field condition requires a field
        name/ID and exactly one operator.
      properties:
        field:
          type: string
          description: Field ID or field name to filter on
        and:
          type: array
          items:
            $ref: '#/components/schemas/FilterCondition'
          description: Array of conditions that must ALL match (logical AND)
        or:
          type: array
          items:
            $ref: '#/components/schemas/FilterCondition'
          description: Array of conditions where ANY must match (logical OR)
        equals:
          description: >-
            Exact match. Supported by: text, number, date, selection, checkbox
            fields.
          oneOf:
            - type: string
            - type: number
            - type: boolean
        does_not_equal:
          description: >-
            Not equal to value. Supported by: text, number, date, selection,
            checkbox fields.
          oneOf:
            - type: string
            - type: number
            - type: boolean
        contains:
          type: string
          description: >-
            Contains substring (text) or has value (multi-select, linked
            record). Supported by: text, selection, linked record fields.
        does_not_contain:
          type: string
          description: >-
            Does not contain substring or value. Supported by: text, selection,
            linked record fields.
        starts_with:
          type: string
          description: 'Starts with string. Supported by: text fields.'
        ends_with:
          type: string
          description: 'Ends with string. Supported by: text fields.'
        is_empty:
          type: boolean
          description: 'Field has no value (pass true). Supported by: all field types.'
        is_not_empty:
          type: boolean
          description: 'Field has a value (pass true). Supported by: all field types.'
        in:
          type: array
          items:
            oneOf:
              - type: string
              - type: number
          description: >-
            Value is in array. Supported by: text, number, selection, linked
            record fields.
        not_in:
          type: array
          items:
            oneOf:
              - type: string
              - type: number
          description: >-
            Value is not in array. Supported by: text, number, selection, linked
            record fields.
        greater_than:
          description: 'Greater than value. Supported by: number, date fields.'
          oneOf:
            - type: number
            - type: string
              format: date
        greater_than_or_equal_to:
          description: 'Greater than or equal to value. Supported by: number, date fields.'
          oneOf:
            - type: number
            - type: string
              format: date
        less_than:
          description: 'Less than value. Supported by: number, date fields.'
          oneOf:
            - type: number
            - type: string
              format: date
        less_than_or_equal_to:
          description: 'Less than or equal to value. Supported by: number, date fields.'
          oneOf:
            - type: number
            - type: string
              format: date
    AggregateGroupResult:
      type: object
      properties:
        value:
          type: number
          nullable: true
          description: The aggregated value for this group. Null when there is no value.
        groupValue:
          nullable: true
          description: The value of the `groupBy` field for this group.
          oneOf:
            - type: string
            - type: number
            - type: boolean
      required:
        - value
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
          required:
            - code
            - message
      required:
        - error
  responses:
    BadRequest:
      description: Invalid request data or validation failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidRecordId:
              value:
                error:
                  code: INVALID_RECORD_ID
                  message: Record ID is not in valid UUID format
            validationError:
              value:
                error:
                  code: BAD_REQUEST
                  message: Invalid request data or validation failure
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key
    NotFound:
      description: Requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: NOT_FOUND
              message: Requested resource does not exist
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Enter your Zite API key. Format: Bearer <api_key>'

````