Skip to main content
POST
/
bases
/
{databaseId}
/
tables
/
{tableId}
/
records
/
list
List records
curl --request POST \
  --url https://tables.fillout.com/api/v1/bases/{databaseId}/tables/{tableId}/records/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sort": [
    {
      "fieldId": "name",
      "direction": "asc"
    },
    {
      "fieldId": "createdAt",
      "direction": "desc"
    }
  ],
  "filter": {
    "and": [
      {
        "field": "Status",
        "equals": "Active"
      },
      {
        "field": "Amount",
        "greater_than": 100
      }
    ]
  },
  "limit": 100,
  "offset": 0
}
'
{
  "records": [
    {
      "id": "d4b3c2a3-c46b-46a1-a8ec-81b664bb41cb",
      "data": {
        "f6JE46z2WoX": "",
        "f5gMv8mk8CX": "",
        "foEBBtqDY1F": false
      },
      "fields": {
        "Name": "",
        "Notes": "",
        "Active": false
      },
      "createdAt": "2025-11-13T11:59:45.000Z",
      "updatedAt": "2025-11-13T11:59:45.000Z"
    }
  ],
  "total": 1250,
  "hasMore": true
}
Fetches records from a table with advanced filtering, sorting, and pagination options using either the table ID or table name.

​
Pagination

ParameterTypeDefaultMax
limitnumber5002000
offsetnumber0-
Use hasMore to determine if additional pages exist. Increment offset by limit for each subsequent request.

​
Sorting

When no sort parameter is provided, records are returned in ascending order by creation time (createdAt ASC). 
{
  "sort": [
    { "fieldId": "name", "direction": "asc" },
    { "fieldId": "createdAt", "direction": "desc" }
  ]
}
PropertyTypeRequiredDescription
fieldIdstringYesField ID or system field name (id, createdAt, updatedAt)
directionstringNo"asc" (default) or "desc"

​
Filtering

Use the filter parameter to query records. Filters support nested AND/OR logic for complex queries. 
{
  "filter": {
    "field": "Status",
    "equals": "Active"
  }
}
Use and or or to combine multiple conditions:
{
  "filter": {
    "and": [
      { "field": "Status", "equals": "Active" },
      { "field": "Amount", "greater_than": 100 }
    ]
  }
}

{
  "filter": {
    "or": [
      { "field": "Status", "equals": "Urgent" },
      { "field": "Priority", "equals": "High" }
    ]
  }
}
Filters can be nested for complex logic:
{
  "filter": {
    "or": [
      { "field": "Status", "equals": "Urgent" },
      {
        "and": [
          { "field": "Priority", "equals": "High" },
          { "field": "Completed", "equals": false }
        ]
      }
    ]
  }
}
OperatorDescriptionExample Value
equalsExact match"Active"
does_not_equalNot equal to"Archived"
containsContains substring (text) or has value (multi-select)"john"
does_not_containDoes not contain"test"
starts_withStarts with string"Mr."
ends_withEnds with string"@gmail.com"
is_emptyField has no valuetrue
is_not_emptyField has a valuetrue
inValue is in array["Active", "Pending"]
not_inValue is not in array["Archived", "Deleted"]
greater_thanGreater than (numbers/dates)100 or "2024-01-01"
greater_than_or_equal_toGreater than or equal100
less_thanLess than50
less_than_or_equal_toLess than or equal50
Field TypeSupported Operators
Text (single_line_text, long_text, email, url, phone_number)equals, does_not_equal, contains, does_not_contain, starts_with, ends_with, is_empty, is_not_empty, in, not_in
Number (number, currency, percent, rating, duration)equals, does_not_equal, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, is_empty, is_not_empty, in, not_in
Date (date, datetime)equals, does_not_equal, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, is_empty, is_not_empty
Selection (single_select, multiple_select)equals, does_not_equal, contains, does_not_contain, is_empty, is_not_empty, in, not_in
Checkboxequals, does_not_equal
Attachments (attachments)is_empty, is_not_empty
Linked Recordcontains, does_not_contain, is_empty, is_not_empty, in, not_in
Filter by single select:
{ "filter": { "field": "Status", "equals": "Active" } }
Filter by number range:
{
  "filter": {
    "and": [
      { "field": "Price", "greater_than_or_equal_to": 10 },
      { "field": "Price", "less_than": 100 }
    ]
  }
}
Filter by date:
{ "filter": { "field": "CreatedAt", "greater_than": "2024-01-01" } }
Filter by multiple values:
{ "filter": { "field": "Status", "in": ["Active", "Pending", "Review"] } }
Filter for empty/non-empty:
{ "filter": { "field": "AssignedTo", "is_not_empty": true } }

Authorizations

​
Authorization
string
header
required

Enter your Fillout API key. Format: Bearer <api_key>

Path Parameters

​
databaseId
string
required

The unique identifier of the database

​
tableId
string
required

The unique identifier of the table. You can also use the table name instead of the ID.

Body

application/json
​
limit
integer
default:500

Number of records to return (default: 500, max: 2000)

Required range: 1 <= x <= 2000
​
offset
integer
default:0

Integer-based offset - Number of records to skip for pagination

Required range: x >= 0
​
sort
object[]

Array of sort objects. When not provided, records are returned in ascending order by creation time (createdAt ASC). All queries include an internal tie-breaker to ensure deterministic ordering across paginated requests.

​
filter
object

Filter condition to query records. Supports nested AND/OR logic. Each condition requires field (field ID or name) and one operator (equals, does_not_equal, contains, greater_than, in, etc.). See Filtering documentation for details.

Example:
{ "field": "Status", "equals": "Active" }

Response

List of records

​
records
object[]
required

Array of records

​
total
integer
required

Total number of records matching the query

​
hasMore
boolean
required

Whether there are more records available beyond this page