Skip to main content
POST
/
v1
/
tables
/
{table}
/
rows
/
find
cURL
curl --request POST \
  --url https://api.botpress.cloud/v1/tables/{table}/rows/find \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-bot-id: <x-bot-id>' \
  --data '
{
  "limit": 100,
  "offset": 0,
  "filter": {},
  "group": {},
  "search": "<string>",
  "select": [
    "<string>"
  ],
  "orderBy": "id",
  "orderDirection": "asc"
}
'
{
  "rows": [
    {
      "id": 123,
      "computed": {},
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "stale": [
        "<string>"
      ],
      "similarity": 123
    }
  ],
  "hasMore": true,
  "offset": 123,
  "limit": 123,
  "warnings": [
    "<string>"
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-bot-id
string
required

Bot id

​
x-integration-id
string

Integration id

​
x-integration-alias
string

Integration alias

​
x-integration-name
string

Integration name

​
x-user-id
string

User Id

​
x-user-role
string

User Role

Path Parameters

​
table
string
required

The table's name or unique identifier for targeting specific table operations.

Body

application/json

The search criteria and filters to apply when searching for rows. This includes conditions, search terms, and pagination options.

​
limit
integer
default:100

Limit for pagination, specifying the maximum number of rows to return.

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

Offset for pagination, specifying where to start returning rows from.

Required range: x >= 0
​
filter
object

Provide a mongodb-like filter to apply to the query. Example: { "name": { "$eq": "John" } }

​
group
object

Group the rows by a specific column and apply aggregations to them. Allowed values: key, avg, max, min, sum, count. Example: { "someId": "key", "orders": ["sum", "avg"] }

​
search
string

Search term to apply to the row search. When using this parameter, some rows which doesn't match the search term will be returned, use the similarity field to know how much the row matches the search term.

Maximum string length: 1024
​
select
string[]

Specify which columns to return in the response. Supports both top-level columns (e.g., "name") and nested attributes using dot notation (e.g., "attributes.price"). System columns (id, createdAt, updatedAt, etc.) are always included. If omitted, all columns are returned.

​
orderBy
string
default:id

Specifies the column by which to order the results. By default it is ordered by id. Build-in columns: id, createdAt, updatedAt

​
orderDirection
enum<string>
default:asc

Specifies the direction of sorting, either ascending or descending.

Available options:
asc,
desc

Response

A collection of rows that match the search criteria, along with metadata such as total count and pagination details.

​
rows
object[]
required
​
hasMore
boolean
required

Flag indicating if there are more rows to fetch.

​
offset
integer
required
​
limit
integer
required
​
warnings
string[]

Alerts for minor issues that don't block the operation but suggest possible improvements.