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
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. |
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:
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:
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/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/ |
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 blankrather thaniswith an empty value.
Examples #
Jobs scheduled in January 2026 that are not closed:
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:
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.