---
title: "Query table rows"
method: POST
path: "/v1/tables/{tableId}/rows/query"
tags: ["Tables"]
---

# Query table rows

`POST /v1/tables/{tableId}/rows/query`

## Request

- Base URL: `https://api.banksync.io`
- URL: `https://api.banksync.io/v1/tables/{tableId}/rows/query`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

The one "rows where …" question. A `filter` tree (and / or / not over clauses that name a field by key, or one hop through a relation as `relation.field`), `search`, `sort`, a saved `viewId` whose filter is merged in, a row page, `groups` with per-group calculations, and `calculations` over the whole filtered set — answered together, so a total beside a page of rows is a total of those rows. Pass `rows: false` to skip the page. A question the schema cannot answer is a 400 `QUERY_REFUSED` whose `details[]` name each offending path; a view that does not exist, or that belongs to someone else, is a 404 `VIEW_NOT_FOUND`.

## Path parameters

- `tableId` string, required: Table ID

## Request body

- object
  - `filter` union: A filter tree shared by tables, dashboards and widgets. A clause names a field by key (or one hop through a relation as `relation.field`), an operator, and a value; groups combine clauses with and / or / not.
    - union
      - object
        - `field` string, required: Field key, or `relation.field` for one hop.
        - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'starts-with' | 'ends-with' | 'between' | 'is-null' | 'is-not-null' | 'matches' | 'has-passed' | 'not-passed', required
        - `value` union
          - union
            - string
            - string, nullable
          - union
            - number
            - number, nullable
          - union
            - boolean
            - boolean, nullable
          - union
            - union[], nullable
              - …
            - union[]
              - …
          - union
            - object, nullable: An inclusive date range.
              - …
            - object: An inclusive date range.
              - …
            - object: An inclusive date range.
              - …
            - object: An inclusive date range.
              - …
            - object: An inclusive date range.
              - …
            - object: An inclusive date range.
              - …
            - object: An inclusive date range.
              - …
          - union
            - object, nullable: An inclusive numeric range.
              - …
            - object: An inclusive numeric range.
              - …
            - object: An inclusive numeric range.
              - …
            - object: An inclusive numeric range.
              - …
            - object: An inclusive numeric range.
              - …
            - object: An inclusive numeric range.
              - …
            - object: An inclusive numeric range.
              - …
          - union
            - object, nullable: A relative date range, resolved when the query runs.
              - …
            - object: A relative date range, resolved when the query runs.
              - …
            - object: A relative date range, resolved when the query runs.
              - …
            - object: A relative date range, resolved when the query runs.
              - …
            - object: A relative date range, resolved when the query runs.
              - …
            - object: A relative date range, resolved when the query runs.
              - …
            - object: A relative date range, resolved when the query runs.
              - …
          - union
            - object, nullable: Compare against another field of the same row, by key.
              - …
            - object: Compare against another field of the same row, by key.
              - …
            - object: Compare against another field of the same row, by key.
              - …
            - object: Compare against another field of the same row, by key.
              - …
            - object: Compare against another field of the same row, by key.
              - …
            - object: Compare against another field of the same row, by key.
              - …
            - object: Compare against another field of the same row, by key.
              - …
          - union
            - object, nullable: Bind to a dashboard filter by id; resolved when the dashboard renders.
              - …
            - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
              - …
            - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
              - …
            - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
              - …
            - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
              - …
            - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
              - …
            - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
              - …
          - union
            - object, nullable: Bind to a query parameter by name; resolved against the widget bindings.
              - …
            - object: Bind to a query parameter by name; resolved against the widget bindings.
              - …
            - object: Bind to a query parameter by name; resolved against the widget bindings.
              - …
            - object: Bind to a query parameter by name; resolved against the widget bindings.
              - …
            - object: Bind to a query parameter by name; resolved against the widget bindings.
              - …
            - object: Bind to a query parameter by name; resolved against the widget bindings.
              - …
            - object: Bind to a query parameter by name; resolved against the widget bindings.
              - …
        - `security` boolean: Server-bound clause: cannot be dropped by a viewer and is enforced at the data plane.
        - `optional` boolean: Skip the clause (treat as passing) for rows where `field` is absent, as opposed to present-but-null. Default false.
      - object
        - `logic` 'and', required
        - `conditions` FilterNode[], required
        - `field` string, required: Field key, or `relation.field` for one hop.
        - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'starts-with' | 'ends-with' | 'between' | 'is-null' | 'is-not-null' | 'matches' | 'has-passed' | 'not-passed', required
        - `value` union
          - string
          - number
          - boolean
          - union[]
            - union
              - …
          - object: An inclusive date range.
            - `start` string, required
            - `end` string, required
          - object: An inclusive numeric range.
            - `min` number, required
            - `max` number, required
          - object: A relative date range, resolved when the query runs.
            - `rel` 'today' | 'yesterday' | '7d' | '30d' | '90d' | '12m' | 'mtd' | 'qtd' | 'ytd', required
          - object: Compare against another field of the same row, by key.
            - `$field` string, required
          - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
            - `$filter` string, required
          - object: Bind to a query parameter by name; resolved against the widget bindings.
            - `$param` string, required
        - `security` boolean: Server-bound clause: cannot be dropped by a viewer and is enforced at the data plane.
        - `optional` boolean: Skip the clause (treat as passing) for rows where `field` is absent, as opposed to present-but-null. Default false.
      - object
        - `logic` 'or', required
        - `conditions` FilterNode[], required
        - `field` string, required: Field key, or `relation.field` for one hop.
        - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'starts-with' | 'ends-with' | 'between' | 'is-null' | 'is-not-null' | 'matches' | 'has-passed' | 'not-passed', required
        - `value` union
          - string
          - number
          - boolean
          - union[]
            - union
              - …
          - object: An inclusive date range.
            - `start` string, required
            - `end` string, required
          - object: An inclusive numeric range.
            - `min` number, required
            - `max` number, required
          - object: A relative date range, resolved when the query runs.
            - `rel` 'today' | 'yesterday' | '7d' | '30d' | '90d' | '12m' | 'mtd' | 'qtd' | 'ytd', required
          - object: Compare against another field of the same row, by key.
            - `$field` string, required
          - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
            - `$filter` string, required
          - object: Bind to a query parameter by name; resolved against the widget bindings.
            - `$param` string, required
        - `security` boolean: Server-bound clause: cannot be dropped by a viewer and is enforced at the data plane.
        - `optional` boolean: Skip the clause (treat as passing) for rows where `field` is absent, as opposed to present-but-null. Default false.
      - object
        - `logic` 'not', required
        - `condition` FilterNode, required (recursive)
        - `field` string, required: Field key, or `relation.field` for one hop.
        - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'starts-with' | 'ends-with' | 'between' | 'is-null' | 'is-not-null' | 'matches' | 'has-passed' | 'not-passed', required
        - `value` union
          - string
          - number
          - boolean
          - union[]
            - union
              - …
          - object: An inclusive date range.
            - `start` string, required
            - `end` string, required
          - object: An inclusive numeric range.
            - `min` number, required
            - `max` number, required
          - object: A relative date range, resolved when the query runs.
            - `rel` 'today' | 'yesterday' | '7d' | '30d' | '90d' | '12m' | 'mtd' | 'qtd' | 'ytd', required
          - object: Compare against another field of the same row, by key.
            - `$field` string, required
          - object: Bind to a dashboard filter by id; resolved when the dashboard renders.
            - `$filter` string, required
          - object: Bind to a query parameter by name; resolved against the widget bindings.
            - `$param` string, required
        - `security` boolean: Server-bound clause: cannot be dropped by a viewer and is enforced at the data plane.
        - `optional` boolean: Skip the clause (treat as passing) for rows where `field` is absent, as opposed to present-but-null. Default false.
    - union
      - object
        - `field` string, required
        - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'starts-with' | 'ends-with' | 'between' | 'is-null' | 'is-not-null' | 'matches' | 'has-passed' | 'not-passed', required
        - `value` union
          - string
          - number
          - boolean
          - unknown
          - union[]
            - union
              - …
          - object
            - `start` string, required
            - `end` string, required
          - object
            - `min` number, required
            - `max` number, required
          - object
            - `rel` 'today' | 'yesterday' | '7d' | '30d' | '90d' | '12m' | 'mtd' | 'qtd' | 'ytd', required
          - object
            - `$filter` string, required
          - object
            - `$param` string, required
          - object
            - `$field` string, required
        - `security` boolean
        - `optional` boolean
        - `logic` 'and' | 'or', required
        - `conditions` FilterNode[], required
      - object
        - `logic` 'and', required
        - `conditions` FilterNode[], required
      - object
        - `logic` 'or', required
        - `conditions` FilterNode[], required
    - union
      - object
        - `field` string, required
        - `op` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'starts-with' | 'ends-with' | 'between' | 'is-null' | 'is-not-null' | 'matches' | 'has-passed' | 'not-passed', required
        - `value` union
          - string
          - number
          - boolean
          - unknown
          - union[]
            - union
              - …
          - object
            - `start` string, required
            - `end` string, required
          - object
            - `min` number, required
            - `max` number, required
          - object
            - `rel` 'today' | 'yesterday' | '7d' | '30d' | '90d' | '12m' | 'mtd' | 'qtd' | 'ytd', required
          - object
            - `$filter` string, required
          - object
            - `$param` string, required
          - object
            - `$field` string, required
        - `security` boolean
        - `optional` boolean
        - `logic` 'not', required
        - `condition` FilterNode, required (recursive)
      - object
        - `logic` 'not', required
        - `condition` FilterNode, required (recursive)
  - `search` string
  - `viewId` string
  - `sort` object[]
    - `field` string, required
    - `direction` 'asc' | 'desc', required
  - `fields` string[]
  - `deleted` boolean
  - `rows` union
    - false
    - object
      - `cursor` string
      - `limit` integer
  - `groups` object
    - `by` object[], required
      - `field` string, required
      - `direction` 'asc' | 'desc'
      - `hideEmpty` boolean
    - `calculations` object
    - `limit` integer
  - `calculations` object

## Response `200`

Rows, groups and calculations over one filtered set

- object
  - `success` true, required
  - `data` object, required
    - `rows` object
      - `items` object[], required
        - `id` string, required
        - `tableId` string, required
        - `version` integer, required
        - `properties` object, required
        - `provenance` union, required
          - object
            - `kind` 'sync', required
            - `feedId` string, required
            - `bankId` string, required
            - `accountId` string
            - `jobId` string
            - `bankWorkspaceId` string
          - object
            - `kind` 'extractor', required
            - `feedId` string, required
            - `jobId` string
          - object
            - `kind` 'user', required
            - `userId` string, required
          - object
            - `kind` 'import', required
            - `importId` string, required
            - `userId` string, required
          - object
            - `kind` 'api', required
            - `clientId` string, required
        - `createdAt` string, required
        - `updatedAt` string, required
        - `deletedAt` string
      - `nextCursor` string, nullable, required
    - `groups` object
      - `items` object[], required
        - `key` object, required
        - `count` integer, required
        - `calculations` object
      - `truncated` boolean, required
    - `calculations` object
  - `meta` object, required
    - `revision` integer, required
    - `inlineItems` integer, required

## Other responses

- `400`: Validation failed, or a read-only field was written — `code` names the refusal and `details[]` the offending field or cell
- `401`: Unauthorized
- `403`: Forbidden — missing scope, insufficient role, or plan limit reached
- `404`: Not found

---

[API](https://skmtc.dev/banksync/apis/banksync-api.md) · [All operations](https://skmtc.dev/banksync/apis/banksync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/banksync/apis/banksync-api/revisions/94465f5ee922?raw)