Records

Search Records

Search for records in the specified table based on filter, sort, and pagination criteria.

POST/databases/{databaseId}/tables/{tableId}/records/search

Request

curl --request POST \
  --url 'https://tables-api.softr.io/api/v1/databases/<databaseId>/tables/<tableId>/records/search' \
  --header 'Softr-Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {
    "condition": {
      "operator": "AND",
      "leftSide": "<string>",
      "rightSide": "<string>",
      "lowerBound": "<string>",
      "upperBound": "<string>",
      "conditions": [
        {}
      ]
    }
  },
  "sorting": [
    {
      "sortingField": "<string>",
      "sortType": "ASC"
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 10
  }
}'

import json
import requests

url = "https://tables-api.softr.io/api/v1/databases/<databaseId>/tables/<tableId>/records/search"
headers = {
  "Softr-Api-Key": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"filter\":{\"condition\":{\"operator\":\"AND\",\"leftSide\":\"<string>\",\"rightSide\":\"<string>\",\"lowerBound\":\"<string>\",\"upperBound\":\"<string>\",\"conditions\":[{}]}},\"sorting\":[{\"sortingField\":\"<string>\",\"sortType\":\"ASC\"}],\"paging\":{\"offset\":0,\"limit\":10}}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://tables-api.softr.io/api/v1/databases/<databaseId>/tables/<tableId>/records/search", {
  method: "POST",
  headers: {
    "Softr-Api-Key": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "filter": {
      "condition": {
        "operator": "AND",
        "leftSide": "<string>",
        "rightSide": "<string>",
        "lowerBound": "<string>",
        "upperBound": "<string>",
        "conditions": [
          {}
        ]
      }
    },
    "sorting": [
      {
        "sortingField": "<string>",
        "sortType": "ASC"
      }
    ],
    "paging": {
      "offset": 0,
      "limit": 10
    }
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://tables-api.softr.io/api/v1/databases/<databaseId>/tables/<tableId>/records/search");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Softr-Api-Key: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"filter\":{\"condition\":{\"operator\":\"AND\",\"leftSide\":\"<string>\",\"rightSide\":\"<string>\",\"lowerBound\":\"<string>\",\"upperBound\":\"<string>\",\"conditions\":[{}]}},\"sorting\":[{\"sortingField\":\"<string>\",\"sortType\":\"ASC\"}],\"paging\":{\"offset\":0,\"limit\":10}}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://tables-api.softr.io/api/v1/databases/<databaseId>/tables/<tableId>/records/search", bytes.NewBuffer([]byte("{\"filter\":{\"condition\":{\"operator\":\"AND\",\"leftSide\":\"<string>\",\"rightSide\":\"<string>\",\"lowerBound\":\"<string>\",\"upperBound\":\"<string>\",\"conditions\":[{}]}},\"sorting\":[{\"sortingField\":\"<string>\",\"sortType\":\"ASC\"}],\"paging\":{\"offset\":0,\"limit\":10}}")))
  req.Header.Set("Softr-Api-Key", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://tables-api.softr.io/api/v1/databases/<databaseId>/tables/<tableId>/records/search"))
    .header("Softr-Api-Key", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"filter\":{\"condition\":{\"operator\":\"AND\",\"leftSide\":\"<string>\",\"rightSide\":\"<string>\",\"lowerBound\":\"<string>\",\"upperBound\":\"<string>\",\"conditions\":[{}]}},\"sorting\":[{\"sortingField\":\"<string>\",\"sortType\":\"ASC\"}],\"paging\":{\"offset\":0,\"limit\":10}}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://tables-api.softr.io/api/v1/databases/<databaseId>/tables/<tableId>/records/search")
request = Net::HTTP::Post.new(uri)
request["Softr-Api-Key"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"filter\":{\"condition\":{\"operator\":\"AND\",\"leftSide\":\"<string>\",\"rightSide\":\"<string>\",\"lowerBound\":\"<string>\",\"upperBound\":\"<string>\",\"conditions\":[{}]}},\"sorting\":[{\"sortingField\":\"<string>\",\"sortType\":\"ASC\"}],\"paging\":{\"offset\":0,\"limit\":10}}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "data": [
    {
      "id": "<string>",
      "tableId": "<string>",
      "fields": {},
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "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.

JSON{
  "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:

JSON{
  "operator": "CONTAINS",
  "leftSide": "field-uuid",
  "rightSide": "search term"
}

Operator	Description	Right Side
`IS`	Equals	single value
`IS_NOT`	Not equals	single value
`GREATER_THAN`	Greater than	number or date
`GREATER_THAN_OR_EQUALS`	Greater than or equal	number or date
`LESS_THAN`	Less than	number or date
`LESS_THAN_OR_EQUALS`	Less than or equal	number or date
`CONTAINS`	String contains	string
`DOES_NOT_CONTAIN`	String does not contain	string
`STARTS_WITH`	String starts with	string
`DOES_NOT_START_WITH`	String does not start with	string
`ENDS_WITH`	String ends with	string
`DOES_NOT_END_WITH`	String does not end with	string
`IS_ONE_OF`	Value is one of	array
`IS_NOT_ONE_OF`	Value is none of	array
`HAS_ANY_OF`	Multi-value field has any of	array
`HAS_ALL_OF`	Multi-value field has all of	array
`HAS_NONE_OF`	Multi-value field has none of	array

Unary Conditions

Check whether a field is empty — no rightSide needed:

JSON{
  "operator": "IS_EMPTY",
  "leftSide": "field-uuid"
}

Operator	Description
`IS_EMPTY`	Field has no value
`IS_NOT_EMPTY`	Field has a value

Ternary Conditions

Range-based checks with lowerBound and upperBound:

JSON{
  "operator": "IS_BETWEEN",
  "leftSide": "field-uuid",
  "lowerBound": 10,
  "upperBound": 100
}

Operator	Description
`IS_BETWEEN`	Value is between bounds (inclusive)
`IS_NOT_BETWEEN`	Value is outside bounds
`IS_WITHIN`	Date is within a relative range
`IS_NOT_WITHIN`	Date is outside a relative range

Composite Conditions

Combine multiple conditions with AND or OR:

JSON{
  "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:

Format	Examples
`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:

JSON{
  "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-KeyAPI key · headerrequired

Path Parameters

databaseIdstringrequired

tableIdstringrequired

Query Parameters

fieldNamesbooleandefault: false

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

Body

application/json

filterobject

Show child attributes

filter.conditionobject

A condition for filtering records. Text-related conditions are case-insensitive.

Show child attributes

filter.condition.operatorenum<string>

Available options: AND, OR, IS_EMPTY, IS_NOT_EMPTY, IS_BETWEEN, IS_NOT_BETWEEN, IS_WITHIN, IS_NOT_WITHIN, IS, IS_NOT, GREATER_THAN, GREATER_THAN_OR_EQUALS, LESS_THAN, LESS_THAN_OR_EQUALS, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, DOES_NOT_START_WITH, ENDS_WITH, DOES_NOT_END_WITH, IS_ONE_OF, IS_NOT_ONE_OF, HAS_ANY_OF, HAS_ALL_OF, HAS_NONE_OF

filter.condition.leftSidestring

The Field ID to apply the operator on.

filter.condition.rightSidestring | number | boolean | string[]

The value to compare against. Can be a string, number, or an array for operators like IS_ONE_OF.

filter.condition.lowerBoundstring

Lower bound for IS_BETWEEN operator.

filter.condition.upperBoundstring

Upper bound for IS_BETWEEN operator.

filter.condition.conditionsobject[]

Used for AND/OR operators to nest conditions.

Show child attributes

filter.condition.conditions.operatorenum<string>

filter.condition.conditions.leftSidestring

The Field ID to apply the operator on.

filter.condition.conditions.rightSidestring | number | boolean | string[]

The value to compare against. Can be a string, number, or an array for operators like IS_ONE_OF.

filter.condition.conditions.lowerBoundstring

Lower bound for IS_BETWEEN operator.

filter.condition.conditions.upperBoundstring

Upper bound for IS_BETWEEN operator.

filter.condition.conditions.conditionsobject[]

Used for AND/OR operators to nest conditions.

Show child attributes

filter.condition.conditions.conditions.operatorenum<string>

filter.condition.conditions.conditions.leftSidestring

The Field ID to apply the operator on.

filter.condition.conditions.conditions.rightSidestring | number | boolean | string[]

The value to compare against. Can be a string, number, or an array for operators like IS_ONE_OF.

filter.condition.conditions.conditions.lowerBoundstring

Lower bound for IS_BETWEEN operator.

filter.condition.conditions.conditions.upperBoundstring

Upper bound for IS_BETWEEN operator.

filter.condition.conditions.conditions.conditionsobject[]

Used for AND/OR operators to nest conditions.

Show child attributes

filter.condition.conditions.conditions.conditions.operatorenum<string>

filter.condition.conditions.conditions.conditions.leftSidestring

The Field ID to apply the operator on.

filter.condition.conditions.conditions.conditions.rightSidestring | number | boolean | string[]

The value to compare against. Can be a string, number, or an array for operators like IS_ONE_OF.

filter.condition.conditions.conditions.conditions.lowerBoundstring

Lower bound for IS_BETWEEN operator.

filter.condition.conditions.conditions.conditions.upperBoundstring

Upper bound for IS_BETWEEN operator.

filter.condition.conditions.conditions.conditions.conditionsobject[]

Used for AND/OR operators to nest conditions.

Show child attributes

filter.condition.conditions.conditions.conditions.conditions.operatorenum<string>

filter.condition.conditions.conditions.conditions.conditions.leftSidestring

The Field ID to apply the operator on.

filter.condition.conditions.conditions.conditions.conditions.rightSidestring | number | boolean | string[]

The value to compare against. Can be a string, number, or an array for operators like IS_ONE_OF.

filter.condition.conditions.conditions.conditions.conditions.lowerBoundstring

Lower bound for IS_BETWEEN operator.

filter.condition.conditions.conditions.conditions.conditions.upperBoundstring

Upper bound for IS_BETWEEN operator.

filter.condition.conditions.conditions.conditions.conditions.conditionsobject[]

Used for AND/OR operators to nest conditions.

sortingobject[]

Show child attributes

sorting.sortingFieldstring

The Field ID to apply the sorting on

sorting.sortTypeenum<string>

Available options: ASC, DESC

pagingobject

Show child attributes

paging.offsetintegerdefault: 0

paging.limitintegerdefault: 10

Response

application/json

A paginated list of matching records.

dataobject[]

Show child attributes

data.idstring

data.tableIdstring

data.fieldsRecord<string, unknown>

A map of Field IDs to their values for this record.

data.createdAtstring<date-time>

data.updatedAtstring<date-time>

metadataobject

Show child attributes

metadata.offsetinteger

metadata.limitinteger

metadata.totalinteger

Search Records

Filtering Guide

Filter Condition Types

Binary Conditions

Unary Conditions

Ternary Conditions

Composite Conditions

Relative Date Values

Complete Example

Authorizations

Path Parameters

Query Parameters

Body

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown