Skip to main content
POST
/
databases
/
{databaseId}
/
tables
/
{tableId}
/
records
/
search
Search Records
curl --request POST \
  --url https://tables-api.softr.io/api/v1/databases/{databaseId}/tables/{tableId}/records/search \
  --header 'Content-Type: application/json' \
  --header 'Softr-Api-Key: <api-key>' \
  --data '
{
  "filter": {
    "condition": {
      "leftSide": "<string>",
      "rightSide": "<string>",
      "lowerBound": "<string>",
      "upperBound": "<string>",
      "conditions": "<array>"
    }
  },
  "sort": [
    {
      "sortingField": "<string>"
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 10
  }
}
'
{
  "data": [
    {
      "id": "<string>",
      "tableId": "<string>",
      "fields": {},
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "metadata": {
    "offset": 123,
    "limit": 123,
    "total": 123
  }
}

​
Filtering Guide

The Search Records endpoint lets you filter, sort, and paginate records using a JSON request body. All three top-level fields (filter, sorting, paging) are optional. 
{
  "paging": {
    "offset": 0,
    "limit": 50
  },
  "sorting": [
    { "sortingField": "field-uuid", "sortType": "ASC" }
  ],
  "filter": {
    "condition": { ... }
  }
}

​
Filter Condition Types

Filters are passed in filter.condition. There are four types, determined by the operator.

​
Binary Conditions

Compare a field to a value: 
{
  "operator": "CONTAINS",
  "leftSide": "field-uuid",
  "rightSide": "search term"
}
OperatorDescriptionRight Side
ISEqualssingle value
IS_NOTNot equalssingle value
GREATER_THANGreater thannumber or date
GREATER_THAN_OR_EQUALSGreater than or equalnumber or date
LESS_THANLess thannumber or date
LESS_THAN_OR_EQUALSLess than or equalnumber or date
CONTAINSString containsstring
DOES_NOT_CONTAINString does not containstring
STARTS_WITHString starts withstring
DOES_NOT_START_WITHString does not start withstring
ENDS_WITHString ends withstring
DOES_NOT_END_WITHString does not end withstring
IS_ONE_OFValue is one ofarray
IS_NOT_ONE_OFValue is none ofarray
HAS_ANY_OFMulti-value field has any ofarray
HAS_ALL_OFMulti-value field has all ofarray
HAS_NONE_OFMulti-value field has none ofarray

​
Unary Conditions

Check whether a field is empty — no rightSide needed: 
{
  "operator": "IS_EMPTY",
  "leftSide": "field-uuid"
}
OperatorDescription
IS_EMPTYField has no value
IS_NOT_EMPTYField has a value

​
Ternary Conditions

Range-based checks with lowerBound and upperBound: 
{
  "operator": "IS_BETWEEN",
  "leftSide": "field-uuid",
  "lowerBound": 10,
  "upperBound": 100
}
OperatorDescription
IS_BETWEENValue is between bounds (inclusive)
IS_NOT_BETWEENValue is outside bounds
IS_WITHINDate is within a relative range
IS_NOT_WITHINDate is outside a relative range

​
Composite Conditions

Combine multiple conditions with AND or OR: 
{
  "operator": "AND",
  "conditions": [
    { "operator": "CONTAINS", "leftSide": "name-field", "rightSide": "acme" },
    { "operator": "GREATER_THAN", "leftSide": "amount-field", "rightSide": 1000 },
    {
      "operator": "OR",
      "conditions": [
        { "operator": "IS", "leftSide": "status-field", "rightSide": "active" },
        { "operator": "IS_EMPTY", "leftSide": "archived-field" }
      ]
    }
  ]
}

​
Relative Date Values

For date fields, you can use relative date strings instead of fixed ISO 8601 dates:
FormatExamples
PREDEFINED:<token>PREDEFINED:TODAY, PREDEFINED:YESTERDAY, PREDEFINED:TOMORROW, PREDEFINED:THIS_WEEK, PREDEFINED:LAST_WEEK, PREDEFINED:THIS_MONTH, PREDEFINED:THIS_YEAR, PREDEFINED:NEXT_MONTH, PREDEFINED:PAST_MONTH, PREDEFINED:7_DAYS_AGO, PREDEFINED:30_DAYS_FROM_NOW
RELATIVE_DATE:<period>:<unit>RELATIVE_DATE:THIS:WEEK, RELATIVE_DATE:PAST:MONTH, RELATIVE_DATE:NEXT:QUARTER, RELATIVE_DATE:PAST:7 (7 days ago)
ISO 8601"2025-05-21", "2025-05-21T20:00:00.000Z"

​
Complete Example

Find active contacts named “acme” with an amount over 1000, created this month: 
{
  "paging": { "offset": 0, "limit": 50 },
  "sorting": [
    { "sortingField": "amount-field-uuid", "sortType": "DESC" }
  ],
  "filter": {
    "condition": {
      "operator": "AND",
      "conditions": [
        { "operator": "CONTAINS", "leftSide": "name-field-uuid", "rightSide": "acme" },
        { "operator": "GREATER_THAN", "leftSide": "amount-field-uuid", "rightSide": 1000 },
        { "operator": "IS", "leftSide": "status-field-uuid", "rightSide": "active" },
        { "operator": "IS_WITHIN", "leftSide": "created-at-field-uuid", "lowerBound": "RELATIVE_DATE:THIS:MONTH", "upperBound": "PREDEFINED:TODAY" }
      ]
    }
  }
}

Authorizations

​
Softr-Api-Key
string
header
required

Path Parameters

​
databaseId
string
required
​
tableId
string
required

Query Parameters

​
fieldNames
boolean
default:false

If true, use field names as keys in the fields object instead of field IDs.

Body

application/json
​
filter
object
​
sort
object[]
​
paging
object

Response

A paginated list of matching records.

​
data
object[]
​
metadata
object