Book a demo

List Records

grist.list_records
ActionDatabases & warehousesconnection required

Calls the Grist API with the connection's credentials.

Read the rows of a table, optionally filtered, sorted and limited.

Ask about GristAll Grist nodesProvider API docs ↗

Connection

Required
Yes — the node will not save without one
Auth type
API key
Providers
Grist
Secret shape
the API key, or {"api_key": "…"}
Config it needs
base_url, doc_id
Resolved by
config.connection_id, else node.connection_id

Configuration

6 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

FieldTypeRequiredDefaultConstraintsExample
table_id
The table to act on, as its table id (the TABLE ID shown in Raw Data).
stringYes——People
doc_id
Document to act in; overrides the document set on the connection.
stringNo——mR9tqLGSKB2Z
filter
Column name to the list of values allowed in it, for example {"pet": ["cat", "dog"]}.
objectNo——{"pet":["cat","dog"]}
sort
Comma-separated column names to order by; prefix one with '-' for descending, as in 'pet,-age'.
stringNo——pet,-age
limit
Return at most this many rows; 0 means no limit.
numberNo0≥ 0—
hidden
Include Grist's hidden columns, such as manualSort, in each record.
booleanNofalse——

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "doc_id": "mR9tqLGSKB2Z",
  "filter": {
    "pet": [
      "cat",
      "dog"
    ]
  },
  "hidden": false,
  "limit": 0,
  "sort": "pet,-age",
  "table_id": "People"
}

Output

One shape.

result

FieldTypeExample
records
One object per row returned.
array—
records[].id
The Grist row id.
number—
records[].fields
Column id to that row's cell value.
object—
count
How many rows the response carried.
number—
table_id
The table id the call acted on.
string—
doc_id
The Grist document the call acted on.
string—
{
  "count": 0,
  "doc_id": "",
  "records": [
    {
      "fields": {},
      "id": 0
    }
  ],
  "table_id": ""
}

Related Grist nodes

See List Records run in a workflow.

In a technical demo we add the Grist connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demoTalk to sales