# Filter records in API requests

> Return only the records you need from the REST API: conditions, AND and OR groups, nested groups, and the operators each field type accepts.

Source: https://tadabase.com/docs/developers/filtering-records  
Status: Verified Nov 17, 2026. Checked against the current product

Add `filters` to the query string of `GET /data-tables/{tableId}/records` to get only the records that match. Each condition names a field, an operator and a value; group conditions with AND or OR, and nest groups for mixed logic.

## Send a filter

Filters go in the query string of a `GET` request. Each condition has three parts:

| Key | Value |
| --- | --- |
| `filters[items][0][field_id]` | The field's slug, such as `field_38`. |
| `filters[items][0][operator]` | An operator from the lists below, written exactly as shown. |
| `filters[items][0][val]` | The value to compare with. Operators such as `is blank` need none. |

```bash
curl -G "https://api.tadabase.io/api/v1/data-tables/{tableId}/records" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  --data-urlencode "filters[items][0][field_id]=field_38" \
  --data-urlencode "filters[items][0][operator]=is" \
  --data-urlencode "filters[items][0][val]=Active"
```

> **Warning:** Send filters with `GET`. A `POST` to `/data-tables/{tableId}/records` does not search: it creates a new record from the body.

## Combine conditions

Add more items with the next index (`filters[items][1][...]`). `filters[condition]` decides how they combine: `AND` (the default) needs every condition to match, `OR` needs any one of them.

For mixed logic, put a group inside `filters[child]`. Each child group has its own `items` and `condition`, and it combines with the top-level conditions using the top-level `condition`. This request returns active records whose email ends in either of two domains:

```text
filters[condition]=AND
filters[items][0][field_id]=field_38
filters[items][0][operator]=is
filters[items][0][val]=Active
filters[child][0][condition]=OR
filters[child][0][items][0][field_id]=field_37
filters[child][0][items][0][operator]=ends with
filters[child][0][items][0][val]=@example.com
filters[child][0][items][1][field_id]=field_37
filters[child][0][items][1][operator]=ends with
filters[child][0][items][1][val]=@example.org
```

> **Warning:** Keep at least one condition in the top-level `items`. A request whose filter holds only `child` groups is not filtered, and every record comes back.

In JavaScript, build the same request with `URLSearchParams`:

```js
const BASE = 'https://api.tadabase.io/api/v1';
const headers = {
  'X-Tadabase-App-id': 'YOUR_APP_ID',
  'X-Tadabase-App-Key': 'YOUR_API_KEY',
  'X-Tadabase-App-Secret': 'YOUR_API_SECRET',
};

const q = new URLSearchParams({
  'filters[condition]': 'AND',
  'filters[items][0][field_id]': 'field_38',
  'filters[items][0][operator]': 'is',
  'filters[items][0][val]': 'Active',
  'filters[child][0][condition]': 'OR',
  'filters[child][0][items][0][field_id]': 'field_37',
  'filters[child][0][items][0][operator]': 'ends with',
  'filters[child][0][items][0][val]': '@example.com',
  'filters[child][0][items][1][field_id]': 'field_37',
  'filters[child][0][items][1][operator]': 'ends with',
  'filters[child][0][items][1][val]': '@example.org',
});
const res = await fetch(`${BASE}/data-tables/${tableId}/records?${q}`, { headers });
const { items, total_items } = await res.json();
```

## Filter on part of a Name, Address or Date Range

Add the part to the slug after a hyphen:

| Field type | Parts |
| --- | --- |
| Name | `field_12-title`, `field_12-first_name`, `field_12-middle_name`, `field_12-last_name` |
| Address | `field_14-address`, `field_14-address2`, `field_14-city`, `field_14-state`, `field_14-zip`, `field_14-country` |
| Date Range | `field_16-start`, `field_16-end` (without a part, the start date is used) |

Without a part, a text operator on a Name or Address field looks at all of its parts.

## Operators by field type

Use these names exactly. They are the operators the filter engine accepts for records read with an API key.

### Text, Email, Phone, Long Text, Rich Text and Link

| Operator | Matches when the field |
| --- | --- |
| `is` | equals the value (upper and lower case count as the same) |
| `is not` | does not equal the value |
| `is exact` | equals the value, with the same upper and lower case |
| `contains` | contains the value anywhere |
| `does not contain` | does not contain the value |
| `starts with` | starts with the value |
| `ends with` | ends with the value |
| `is blank` | is empty |
| `is not blank` | has a value |
| `character length is greater than` | has more characters than the number in `val` |
| `character length is less then` | has fewer characters than the number in `val` (the operator is spelled this way) |

`starts with` and `ends with` compare the text of a Rich Text field without its HTML, and only the digits of a Phone field.

### Number, Currency, Rating, and numeric Equation and Rollup fields

| Operator | Matches when the field |
| --- | --- |
| `is`, `is not` | equals, or does not equal, the number |
| `higher than`, `lower than` | is greater than, or less than, the number |
| `higher than or equal to`, `lower than or equal to` | is at least, or at most, the number |
| `is blank`, `is not blank` | is empty, or has a value |

### Select, Radio, Multi-Select and Checkbox

| Operator | Matches when the field |
| --- | --- |
| `is`, `contains` | has the option in `val` |
| `is not`, `does not contain` | does not have the option |
| `is blank`, `is not blank` | has no option chosen, or has one |

To match any of several options, send `val` as a list: `filters[items][0][val][]=Open&filters[items][0][val][]=Pending`.

### Decision Box

| Operator | Matches when the box |
| --- | --- |
| `is checked` | is checked |
| `is unchecked` | is not checked |
| `is` | matches `val`: `1`, `yes` or `true` for checked, anything else for unchecked |

### Date, Date/Time, Time and Date Range

| Operator | Matches when the date |
| --- | --- |
| `is`, `is not` | is, or is not, the value. For a Date/Time field `is` needs the same minute. |
| `is before`, `is after` | is earlier, or later, than the value |
| `is on or before`, `is on or after` | is the value or earlier, or the value or later |
| `is between` | falls between `val` and `val2`, both included (Date, Date/Time and Date Range only) |
| `is blank`, `is not blank` | is empty, or has a value |
| `is today`, `is not today`, `is before today`, `is after today`, `is today or before`, `is today or after` | compares with today |
| `is before current time`, `is after current time` | compares with the current time |
| `is this week`, `is this month`, `is this quarter`, `is this year` | falls in the current period (`is not this week` and so on for the opposite) |
| `is last week`, `is last month`, `is last quarter`, `is last year` | falls in the previous period (`is not last week` and so on) |
| `is next week`, `is next month`, `is next quarter`, `is next year` | falls in the next period (`is not next week` and so on) |
| `is during the current` | falls in the current period named in `val2`: `week`, `month`, `quarter` or `year` |
| `is during the previous`, `is during the next` | falls in the last, or next, `val2` units, where `val3` is `days`, `weeks`, `months` or `years` |
| `is before the previous`, `is after the next` | is earlier than the last, or later than the next, `val2` units of `val3` |

Send dates as `YYYY-MM-DD` (add ` HH:MM` for a time), or in the date format set for your app.

### Connection

| Operator | Matches when the record |
| --- | --- |
| `is`, `is not` | is, or is not, connected to the record ID in `val`. Separate several IDs with commas to match any of them. |
| `contains`, `does not contain` | is connected to a record whose display value contains, or does not contain, the text |
| `is blank`, `is not blank` | has no connected record, or has at least one |

Operators that depend on a signed-in user or on the current page, such as `is logged in user`, match no records in a call made with only an API key.

## When a filter is refused or ignored

- A condition on a field that is not in this table answers HTTP 400, for example "Filter field field_99 isn't a field of this table." A field that was deleted gets a message pointing to Deleted Fields.
- An operator name that is not in the lists above is ignored, so that condition filters nothing. Copy operator names exactly.
- To find empty fields, use `is blank` rather than `is` with an empty value.

## Examples

Jobs scheduled in January 2026 that are not closed:

```text
filters[items][0][field_id]=field_51
filters[items][0][operator]=is between
filters[items][0][val]=2026-01-01
filters[items][0][val2]=2026-01-31
filters[items][1][field_id]=field_52
filters[items][1][operator]=is not
filters[items][1][val]=Closed
```

Invoices over 500 created in the last 30 days:

```text
filters[items][0][field_id]=field_61
filters[items][0][operator]=higher than
filters[items][0][val]=500
filters[items][1][field_id]=field_62
filters[items][1][operator]=is during the previous
filters[items][1][val2]=30
filters[items][1][val3]=days
```
