---
title: "Count records"
method: GET
path: "/api/v1/records/count"
tags: ["Records"]
---

# Count records

`GET /api/v1/records/count`

## Request

- Base URL: `https://api-docs.busabase.com`
- URL: `https://api-docs.busabase.com/api/v1/records/count`
- Auth: none declared

A real SQL COUNT — always the exact total, never a partial or capped number, so it's safe to render as a canonical figure (e.g. a dashboard summary tile). Plain `baseId` scoping is always cheap. Adding `viewId` and/or `filters` is exact too — provably-exact conditions (e.g. text equals/contains, not_empty/is_empty, checkbox is_true/is_false) stay a cheap SQL COUNT; everything else falls back to evaluating every matching row server-side, which is exact but not free on a large Base. Both `viewId` and `filters` require `baseId`.

## Query parameters

- `baseId` string: Restrict to one Base. Omitting it counts every record in the space. Required as soon as `viewId`, `filters` or `valueFilters` is given — a field slug only means something within one Base.
- `viewId` string: Count only what this saved View would display. Its filters apply; its sort is ignored, since a count has no order. Requires `baseId`.
- `filters` object[]: Ad-hoc conditions, ANDed with the View's own when `viewId` is also given. Unlike `records.list`'s superset `filters`, the COUNT is exact either way — but a condition whose exactness cannot be proven makes the server read every candidate row instead of running one aggregate, so prefer `valueFilters` where it fits. Requires `baseId`.
  - `fieldSlug` string, required
  - `fieldType` string
  - `operator` 'contains' | 'equals' | 'not_empty' | 'is_empty' | 'is_true' | 'is_false', required
  - `value` unknown
- `valueFilters` union[]: EXACT value comparisons, same shape as `records.list`'s. Always exact, so a count scoped only by these stays a single SQL count instead of reading every candidate row. Requires `baseId`.
  - union
    - object
      - `fieldSlug` string, required
      - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte', required
      - `value` union, required
        - number
        - string
        - boolean
    - object
      - `any` object[], required
        - `fieldSlug` string, required
        - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte', required
        - `value` union, required
          - number
          - string
          - boolean

## Response `200`

Total active records matching the scope: the whole space, one Base, a saved View, an ad-hoc filter set, or a combination.

- object
  - `total` integer, required

---

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