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.

  • Verified Nov 17, 2026
  • Classic builder

On this page
  1. Send a filter
  2. Combine conditions
  3. Filter on part of a Name, Address or Date Range
  4. Operators by field type
  5. When a filter is refused or ignored
  6. Examples

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:

KeyValue
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.
Shell
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"

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

In JavaScript, build the same request with URLSearchParams:

JavaScript
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 typeParts
Namefield_12-title, field_12-first_name, field_12-middle_name, field_12-last_name
Addressfield_14-address, field_14-address2, field_14-city, field_14-state, field_14-zip, field_14-country
Date Rangefield_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 #

OperatorMatches when the field
isequals the value (upper and lower case count as the same)
is notdoes not equal the value
is exactequals the value, with the same upper and lower case
containscontains the value anywhere
does not containdoes not contain the value
starts withstarts with the value
ends withends with the value
is blankis empty
is not blankhas a value
character length is greater thanhas more characters than the number in val
character length is less thenhas 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 #

OperatorMatches when the field
is, is notequals, or does not equal, the number
higher than, lower thanis greater than, or less than, the number
higher than or equal to, lower than or equal tois at least, or at most, the number
is blank, is not blankis empty, or has a value

Select, Radio, Multi-Select and Checkbox #

OperatorMatches when the field
is, containshas the option in val
is not, does not containdoes not have the option
is blank, is not blankhas 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 #

OperatorMatches when the box
is checkedis checked
is uncheckedis not checked
ismatches val: 1, yes or true for checked, anything else for unchecked

Date, Date/Time, Time and Date Range #

OperatorMatches when the date
is, is notis, or is not, the value. For a Date/Time field is needs the same minute.
is before, is afteris earlier, or later, than the value
is on or before, is on or afteris the value or earlier, or the value or later
is betweenfalls between val and val2, both included (Date, Date/Time and Date Range only)
is blank, is not blankis empty, or has a value
is today, is not today, is before today, is after today, is today or before, is today or aftercompares with today
is before current time, is after current timecompares with the current time
is this week, is this month, is this quarter, is this yearfalls 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 yearfalls in the previous period (is not last week and so on)
is next week, is next month, is next quarter, is next yearfalls in the next period (is not next week and so on)
is during the currentfalls in the current period named in val2: week, month, quarter or year
is during the previous, is during the nextfalls in the last, or next, val2 units, where val3 is days, weeks, months or years
is before the previous, is after the nextis 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 #

OperatorMatches when the record
is, is notis, or is not, connected to the record ID in val. Separate several IDs with commas to match any of them.
contains, does not containis connected to a record whose display value contains, or does not contain, the text
is blank, is not blankhas 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

Was this page helpful?

Something wrong or missing on this page? Tell us.