> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Airtable

> Prepare for the Airtable integration beta, available November 2, 2026: record intake, task follow-ups, and controlled write-back.

> [!NOTE]
>
> **Beta coming November 2, 2026.** Airtable intake and write-back will be available in beta from this date. **Access:** Must be enabled for your organization. Contact your Gradial team to get access. The setup and workflows below describe the upcoming beta.

## What the beta includes

Connect an Airtable intake table to a Gradial workspace. Each ready record becomes one linked Gradial Task, with Airtable remaining the system of record.

* Choose a table, an optional intake view, and checkbox or single-select triggers.
* Map the record's title, brief, and requester into the Task.
* Follow up on the same Task by mentioning the integration user in a record comment or rearming a configured trigger.
* Let Grady update fields reserved for Gradial, post comments, and append Word drafts to designated attachment fields.

Gradial uses scheduled polling, approximately every five minutes. A running poll finishes before another starts, and larger tables can take longer. This interval is not a guaranteed processing time. The beta does not use Airtable webhooks.

## Prerequisites

* Permission to manage Gradial settings and integrations.
* A Gradial workspace and Environment for incoming Tasks.
* A dedicated Airtable integration user named **Gradial**, with access to the intake bases and the record, field, and comment permissions needed for the workflows below.
* A personal access token belonging to that integration user, limited to the intended bases.
* At least one checkbox or single-select field in each intake table to mark records ready.

> [!WARNING]
>
> Use a dedicated integration user. Gradial posts comments as the token owner and ignores that user's comments when looking for new requests. If you use your personal token, your own comments will not request follow-up work.

### Create the Airtable token

In Airtable's [Developer Hub](https://airtable.com/create/tokens), create a personal access token for the integration user. Add the following scopes and select only the bases Gradial should use:

| Scope | Purpose |
| - | - |
| `schema.bases:read` | Discover bases, tables, views, and fields for setup |
| `data.records:read` | Read intake records and their attachment metadata |
| `data.records:write` | Update designated output fields and append draft files |
| `data.recordComments:read` | Read record comments and follow-up mentions |
| `data.recordComments:write` | Post questions and results on the record |

A token's scopes and selected resources do not grant permissions its owner lacks. Check the integration user's access and any field or table editing restrictions too. See Airtable's [token setup](https://support.airtable.com/docs/creating-personal-access-tokens) and [scope reference](https://airtable.com/developers/web/api/scopes).

## Set up the integration

These steps will be available with the November 2 beta.

**1. Connect Airtable**

Open **Settings → Integrations** and choose **Airtable**. Enter an **Integration name** and paste the token into **Airtable service user personal access token**. Select **Validate connection**, check the returned account, and continue to **Routing**.

**2. Choose the intake table**

Add a route and select a **Base**, then a **Table**. Each route targets one table; add another route for another table. A table can belong to only one route in your organization. Choose an optional **View** to narrow new intake, such as a view that excludes requests on hold.

**3. Set readiness triggers**

Under **Ready records**, add at least one **Trigger field**. A checkbox matches when checked. For a single-select field, choose the **Ready values** that should admit work. A record is ready when **any** configured trigger matches; multiple triggers do not create separate Tasks for the same record. A view alone is not a readiness trigger.

**4. Map request and output fields**

Configure the field mappings below. Keep request inputs separate from fields reserved for Gradial's output.

**5. Choose the destination and review**

Select the destination **Workspace** and **Environment**. Use **Test query** to inspect matching records and resolve mapping issues. Review the **Route summary**, confirm the destinations and results, and save the integration. Query results check the intake selection; they do not establish that comments or file uploads have been exercised.

### Field mappings

| Setting | How to use it |
| - | - |
| **Title field** | Use the request name as the Task title. Defaults to the table's primary field. |
| **Description fields** | Select the brief fields; each becomes a labeled section of the Task description. |
| **Requester field** | Optionally identify the requester with an email, collaborator, or created-by field. |
| **Gradial-owned fields** | Reserve ordinary output fields for Grady to update, such as result status or a preview link. Request inputs cannot also be Gradial-owned. Computed and linked-record fields are not writable outputs. |
| **Append-only file fields** | Designate attachment fields for new drafts. These must be separate from request inputs and Gradial-owned fields. Existing files are not removed or replaced. |

Gradial-owned and append-only file fields are excluded from the synchronized request snapshot, so output changes do not look like new request input. Grady can read them on demand.

## Run and follow up on a request

1. Fill in the record's request fields and input attachments, then set a configured trigger to a ready value.
2. On a scheduled poll, Gradial discovers the ready record and creates its linked Task in the route's destination.
3. Grady processes the request and can write permitted results back to that record as the integration user.
4. For another pass, add a new comment that mentions the actual **Gradial integration user** using Airtable's mention picker. Alternatively, change a configured trigger that Gradial does not own to a new ready value. For a checkbox, clear it, let a poll observe it unchecked, and check it again. For a single-select trigger, select a different configured ready option, or let a poll observe a non-ready value before returning to a ready one. Renaming an option is not a new request.

A follow-up uses the existing linked Task. Ordinary cell edits, an unchanged ready trigger, clearing a trigger, and edits to Gradial-owned fields do not start another run. An off/on change entirely between polls may not be observed.

Gradial continues checking a linked record for follow-up comments after its trigger is cleared or it leaves the intake view, provided the route stays enabled and the Task remains in the route's current Workspace and Environment. Disabling, disconnecting, or rerouting the integration can revoke that access.

## Write-back and file limits

* Grady can read records only in enabled routed tables associated with the Task's Workspace and Environment. It can write only to records linked to that Task.
* Field updates are limited to the route's **Gradial-owned fields**. Grady cannot set an intake trigger to ready; it can clear a trigger only if that field is Gradial-owned.
* Comments are plain text and appear as the integration user. They are visible to people with access to the record.
* Draft uploads are new **`.docx` files up to 5 MB**, with a new versioned filename, in a designated **Append-only file field**. Existing files are not removed or replaced. Those output files are available to Grady on demand rather than automatically copied into the request snapshot.
* Record creation or deletion, schema changes, attachment removal or replacement, and webhook management are outside the beta's command surface.
* Access uses the integration user's Airtable permissions. Gradial does not map each Gradial user's individual Airtable edit permissions.

If a comment or upload has an uncertain outcome, check the Airtable record before asking Grady to submit it again.

## Troubleshooting

| Issue | What to check |
| - | - |
| Airtable is missing from the catalog | Confirm beta access with your Gradial team. Availability begins November 2, 2026. |
| No bases or tables appear | Check the token's base access, `schema.bases:read`, and the integration user's permissions. Use **Refresh bases** or retry the schema read. |
| A table is already routed | Edit its existing route, or remove that route before assigning the table elsewhere. |
| A mapping or ready value is invalid | Refresh the schema and review the selected fields and current single-select options. |
| A record does not become a Task | Confirm the route is enabled, the record belongs to the selected table/view, and at least one trigger matches. Allow for scheduled polling. |
| A comment does not request follow-up work | Mention the actual integration user on the linked record. Comments posted by the token owner are ignored for wake-up. |
| An update or upload is refused | Check the current route and destination, field ownership, file type/size/name, and the integration user's permissions. |
| The token was revoked or regenerated | Contact your Gradial team to replace and revalidate the connection while preserving the existing integration and record links. Saved credentials cannot be edited in the setup wizard. |

Contact your Gradial team for help preparing your intake table or joining the beta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.