Grouping & Saved Views

Three ways to get more out of one list request: summarise it, reuse a stored configuration, and reach rows that have been deleted.

Grouping & aggregation

groupBy partitions records by a field's value; aggregate computes summary functions. Combined, they produce grouped roll-ups such as total amount per status.

GET /api/tables/orders/records?groupBy=status
GET /api/tables/orders/records?aggregate=amount:sum,amount:count,quantity:avg
GET /api/tables/orders/records?groupBy=status&aggregate=amount:sum

Each aggregate entry is field:function — the field first, the function second. Supported functions are sum, count, avg, min and max.

A JSON form is also accepted: ?aggregate={"count":true,"sum":["amount"]}.

Without aggregate, groupBy returns groups: [{ name, count }]. With it, each group additionally carries aggregations.

Saved views

A view bundles a filter tree and a sort order under a stable id, so a recurring query is one parameter rather than a re-encoded expression on every request.

GET /api/tables/tasks/records?view=2

?view= matches on either the view's id or its name. A value matching neither — or any view reference against a table declaring no views — returns 404 NOT_FOUND with "View '<x>' not found".

tables:
  - id: 1
    name: tasks
    views:
      - id: 2
        name: Active Tasks
        filters:
          and:
            - field: status
              operator: in
              value: [todo, in_progress]
        sorts:
          - field: priority
            direction: desc

Two rules govern how explicit parameters interact with the view, and they differ:

Aspect	Behaviour
filter	Merged with the view's filter using and — the request can only narrow.
sort	Replaces the view's sort entirely when present.
fields	The view's field configuration is ignored on this endpoint.
groupBy	The view's grouping is ignored on this endpoint.

Including deleted records

Soft-deleted rows are excluded by default. Two parameters reach them:

Parameter	Result
?includeDeleted=true	Active and deleted rows in one listing.
?deleted=true	Deleted rows only — a trash listing.

includeDeleted is compared against the exact string true; any other value, including only, is treated as "exclude deleted". Trash-only is ?deleted=true, or the dedicated GET /api/tables/:tableId/trash endpoint.

GET /api/tables/tasks/records?includeDeleted=true
GET /api/tables/tasks/records?deleted=true

See Soft Delete & Restore for the full recovery workflow.

Related pages

• Filtering, Sorting & Pagination — the rest of the list query grammar.
• Table Views — declaring saved filter/sort/field configurations.
• Soft Delete & Restore — trash, restore, and cascades.
• Records Overview — list envelope and cross-cutting rules.
• Analytics — pre-built aggregates over usage rather than records.