Grist

Read and write the records in your Grist documents, and build the tables and columns that hold them.

Actions

Action	What it does
Add a column	Add one column of a particular type to a table.
Add a record	Add a record to a table.
Add or update a record	Find the record whose column holds a given value and update it, or add it when there is no such record.
Create a document	Create an empty document in one of your workspaces.
Create a table	Add a table to a document, naming the columns it starts with.
Delete a record	Permanently remove one record from a table.
Export a table as CSV	Get a whole table as CSV text, formatted the way Grist shows it, ready to attach to an email or save as a file.
Find records	Get records from a table.
Get a document	Get a document's name, where it lives, and a link that opens it.
Get a record	Get one record by its ID.
List columns	List a table's columns: what each is called, what it holds, and the choices a choice column allows.
List documents	List every Grist document this connection can open, across your personal area and any team sites.
List tables	List the tables in a document, with the ID each one is known by.
List workspaces	List the workspaces documents are kept in, across your personal area and any team sites.
Run a SQL query	Run a read-only SELECT across a document's tables: totals, date ranges, and joins that the record actions cannot express.
Update a record	Change some columns of one record.

Add a column

Add one column of a particular type to a table.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.
Column namecolumn_nametextRequired: What to call the new column, for example 'Renewal date'.
Column typecolumn_typetextRequired: What the column holds.One of: text, number, whole_number (Whole number), toggle (Toggle (yes or no)), date, datetime (Date & time), choice (One choice from a list), choice_list (Several choices from a list), reference (A link to a record in another table), reference_list (Links to records in another table), attachments, any (Anything (Grist works it out)). Default: text.
Choiceschoiceslist: The values this column allows. Only used when the column holds one or several choices.
Linked tablelinked_tabletext: The table this column points at. Only used when the column links to another table.
Time zonetime_zonetext: The time zone a date & time column displays in, for example Europe/Paris. Defaults to UTC.

Outputs

choiceslist: The choices it allows, for a choice column.
idtext: The column ID used in record values.
links_totext: The table it points at, for a link column.
nametext: The name it was given.
table_idtext: The table it was added to.
typetext: What it holds.

Example output

{
  "id": "Renewal_date",
  "name": "Renewal date",
  "table_id": "Deals",
  "type": "Date"
}

Add a record

Add a record to a table. The record comes back as Grist stored it, including its new record ID.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.
Column valuesfieldsobjectRequired: The value for each column. Leave a column blank to leave it empty. Dates go in as 2026-03-01 (and times as 2026-03-01T09:30:00), and a choice-list or link-list column takes a list of values.

Outputs

errorsobject: Only present when a formula column failed: the column and the error.
fieldsobject: The record's column values, keyed by column ID.
idnumber: The record's ID, which the other record actions take.

Example output

{
  "fields": {
    "Amount": 1250,
    "Customer": "Acme Inc.",
    "Due": "2026-03-01",
    "Status": "Open",
    "Tags": [
      "Priority",
      "Renewal"
    ]
  },
  "id": 3
}

Add or update a record

Find the record whose column holds a given value and update it, or add it when there is no such record. The result says which happened.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.
Match columnmatch_columntextRequired: The column that identifies the record, such as an email address or an order number.
Match valuematch_valuetextRequired: The value that column must hold.
Column valuesfieldsobjectRequired: The values to set on the record, whether it is found or created. Leave a column blank to leave it alone.

Outputs

createdtrue/false: True when the record was added, false when an existing one was updated.
errorsobject: Only present when a formula column failed: the column and the error.
fieldsobject: The record's column values, keyed by column ID.
idnumber: The record's ID, which the other record actions take.

Example output

{
  "created": false,
  "fields": {
    "Amount": 1250,
    "Customer": "Acme Inc.",
    "Due": "2026-03-01",
    "Status": "Open",
    "Tags": [
      "Priority",
      "Renewal"
    ]
  },
  "id": 3
}

Create a document

Create an empty document in one of your workspaces.

Inputs

Workspaceworkspace_idtextRequired: The workspace to create the document in.
Document namedocument_nametextRequired: What to call the new document.

Outputs

idtext: The document ID the other actions take.
nametext: The name it was given.
teamtext: The team site or personal area.
urltext: A link that opens the document.
workspacetext: The workspace holding it.

Example output

{
  "id": "9PJhBDZPyCNoayZxaCwFfS",
  "name": "Q2 campaign",
  "team": "Acme",
  "url": "https://acme.getgrist.com/9PJhBDZPyCNoayZxaCwFfS",
  "workspace": "Marketing"
}

Create a table

Add a table to a document, naming the columns it starts with. Each column takes its type from the first value put in it.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Table nametable_nametextRequired: What to call the new table, for example 'Customer notes'.
Column namescolumn_nameslistRequired: One name per column, in the order they should appear.

Outputs

columnslist: The columns it was created with.
idtext: The table ID the other actions take.
nametext: The name it was given.

Example output

{
  "columns": [
    {
      "id": "Customer",
      "name": "Customer"
    },
    {
      "id": "Note",
      "name": "Note"
    }
  ],
  "id": "Customer_notes",
  "name": "Customer notes"
}

Delete a record

Permanently remove one record from a table.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.
Record IDrecord_idnumberRequired: The record's ID in Grist. 'Find records' returns it as 'id', and adding a record hands it back.At least 1.

Outputs

deletedtrue/false: Whether the record was removed.
idnumber: The ID of the record that was removed.

Example output

{
  "deleted": true,
  "id": 3
}

Export a table as CSV

Get a whole table as CSV text, formatted the way Grist shows it, ready to attach to an email or save as a file.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.

Outputs

columnslist: The column names in the header row.
csvtext: The table as CSV text, with the column names on the first line.
row_countnumber: How many records the file holds.
table_idtext: The table that was exported.

Example output

{
  "columns": [
    "Customer",
    "Status",
    "Amount"
  ],
  "csv": "Customer,Status,Amount\nAcme Inc.,Open,1250\n",
  "row_count": 1,
  "table_id": "Deals"
}

Find records

Get records from a table. Match one column against one or more values, or leave the column blank to get everything.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.
Match columncolumntext: The column to match on. Leave blank to return every record.
Match valuesvalueslist: A record is returned when the column holds any one of these. Dates go in as 2026-03-01.
Sort bysort_columntext: The column to order the results by. Leave blank to keep Grist's order.
Ordersort_directiontext: Which way to sort.One of: ascending (A → Z, smallest and oldest first), descending (Z → A, largest and newest first). Default: ascending.
Maximum recordslimitnumber: The most records to return. Leave blank to return all of them.At least 1.

Outputs

countnumber: How many records came back.
recordslist: The matching records.

Example output

{
  "count": 1,
  "records": [
    {
      "fields": {
        "Amount": 1250,
        "Customer": "Acme Inc.",
        "Due": "2026-03-01",
        "Status": "Open",
        "Tags": [
          "Priority",
          "Renewal"
        ]
      },
      "id": 3
    }
  ]
}

Get a document

Get a document's name, where it lives, and a link that opens it.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.

Outputs

accesstext: Your access to it.
idtext: The document ID.
nametext: The document's name.
teamtext: The team site or personal area.
updated_attext: When the document last changed.
urltext: A link that opens the document.
workspacetext: The workspace holding it.

Example output

{
  "access": "owners",
  "id": "9PJhBDZPyCNoayZxaCwFfS",
  "name": "Sales pipeline",
  "team": "Acme",
  "updated_at": "2026-02-14T09:12:44.000Z",
  "url": "https://acme.getgrist.com/9PJhBDZPyCNo",
  "workspace": "Revenue"
}

Get a record

Get one record by its ID.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.
Record IDrecord_idnumberRequired: The record's ID in Grist. 'Find records' returns it as 'id', and adding a record hands it back.At least 1.

Outputs

errorsobject: Only present when a formula column failed: the column and the error.
fieldsobject: The record's column values, keyed by column ID.
idnumber: The record's ID, which the other record actions take.

Example output

{
  "fields": {
    "Amount": 1250,
    "Customer": "Acme Inc.",
    "Due": "2026-03-01",
    "Status": "Open",
    "Tags": [
      "Priority",
      "Renewal"
    ]
  },
  "id": 3
}

List columns

List a table's columns: what each is called, what it holds, and the choices a choice column allows.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.

Outputs

columnslist: The table's columns, in the order Grist shows them.
countnumber: How many columns there are.

Example output

{
  "columns": [
    {
      "id": "Customer",
      "is_formula": false,
      "name": "Customer",
      "type": "Text"
    },
    {
      "choices": [
        "Open",
        "Won",
        "Lost"
      ],
      "id": "Status",
      "is_formula": false,
      "name": "Status",
      "type": "Choice"
    },
    {
      "id": "Due",
      "is_formula": false,
      "name": "Due",
      "type": "Date"
    }
  ],
  "count": 3
}

List documents

List every Grist document this connection can open, across your personal area and any team sites.

Inputs

None.

Outputs

countnumber: How many documents there are.
documentslist: The documents, newest workspace first.

Example output

{
  "count": 1,
  "documents": [
    {
      "access": "owners",
      "id": "9PJhBDZPyCNoayZxaCwFfS",
      "name": "Sales pipeline",
      "team": "Acme",
      "url": "https://acme.getgrist.com/9PJhBDZPyCNo",
      "workspace": "Revenue"
    }
  ]
}

List tables

List the tables in a document, with the ID each one is known by. The summary tables Grist derives for charts and totals are left out.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.

Outputs

countnumber: How many tables there are.
tableslist: The document's tables.

Example output

{
  "count": 2,
  "tables": [
    {
      "id": "Deals",
      "name": "Deals"
    },
    {
      "id": "Customer_Notes",
      "name": "Customer Notes"
    }
  ]
}

List workspaces

List the workspaces documents are kept in, across your personal area and any team sites. This is where 'Create a document' gets the workspace to put a new document in.

Inputs

None.

Outputs

countnumber: How many workspaces there are.
workspaceslist: The workspaces, personal area first.

Example output

{
  "count": 1,
  "workspaces": [
    {
      "access": "owners",
      "document_count": 4,
      "id": 7,
      "name": "Home",
      "team": "Personal"
    }
  ]
}

Run a SQL query

Run a read-only SELECT across a document's tables: totals, date ranges, and joins that the record actions cannot express. Nothing in the document can be changed by it.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
QueryquerytextRequired: A single SELECT statement, using table and column IDs, for example: select Customer, Amount from Deals where Status = ?
Values for ?valueslist: One value for each ? in the query, in order. Use these rather than pasting values into the query itself.

Outputs

countnumber: How many rows came back.
querytext: The statement that was run.
rowslist: The rows the query selected. Values come straight from storage, so a toggle reads 0 or 1 and a date reads as seconds since 1970.

Example output

{
  "count": 1,
  "query": "select Status, sum(Amount) as total from Deals group by Status",
  "rows": [
    {
      "Status": "Open",
      "total": 4300
    }
  ]
}

Update a record

Change some columns of one record. Columns left blank keep the values they already have.

Inputs

Documentdoc_idtextRequired: The Grist document to work in.
Tabletable_idtextRequired: The table to work in.
Record IDrecord_idnumberRequired: The record's ID in Grist. 'Find records' returns it as 'id', and adding a record hands it back.At least 1.
Column valuesfieldsobjectRequired: The columns to change and their new values. Leave a column blank to keep the value it already has. Dates go in as 2026-03-01 (and times as 2026-03-01T09:30:00), and a choice-list or link-list column takes a list of values.

Outputs

errorsobject: Only present when a formula column failed: the column and the error.
fieldsobject: The record's column values, keyed by column ID.
idnumber: The record's ID, which the other record actions take.

Example output

{
  "fields": {
    "Amount": 1250,
    "Customer": "Acme Inc.",
    "Due": "2026-03-01",
    "Status": "Open",
    "Tags": [
      "Priority",
      "Renewal"
    ]
  },
  "id": 3
}

ActionsCopy Anchor Link

Add a columnCopy Anchor Link

Inputs

Outputs

Add a recordCopy Anchor Link

Inputs

Outputs

Add or update a recordCopy Anchor Link

Inputs

Outputs

Create a documentCopy Anchor Link

Inputs

Outputs

Create a tableCopy Anchor Link

Inputs

Outputs

Delete a recordCopy Anchor Link

Inputs

Outputs

Export a table as CSVCopy Anchor Link

Inputs

Outputs

Find recordsCopy Anchor Link

Inputs

Outputs

Get a documentCopy Anchor Link

Inputs

Outputs

Get a recordCopy Anchor Link

Inputs

Outputs

List columnsCopy Anchor Link

Inputs

Outputs

List documentsCopy Anchor Link

Inputs

Outputs

List tablesCopy Anchor Link

Inputs

Outputs

List workspacesCopy Anchor Link

Inputs

Outputs

Run a SQL queryCopy Anchor Link

Inputs

Outputs

Update a recordCopy Anchor Link

Inputs

Outputs

On this page

Actions

Add a column

Add a record

Add or update a record

Create a document

Create a table

Delete a record

Export a table as CSV

Find records

Get a document

Get a record

List columns

List documents

List tables

List workspaces

Run a SQL query

Update a record