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

# Airtable

> Connect Airtable bases to your Agent

## Overview

The Airtable integration lets your agents discover, read, and write records across your Airtable workspaces. Works with any standard or custom table — agents can enumerate the bases they have access to, inspect fields at runtime, and perform full CRUD operations, including batch upserts.

## Features

* **Dynamic Discovery**: Agents can list accessible bases and inspect table schemas (fields, types, select choices, views) without hardcoded configuration
* **Flexible Search**: Three query modes — free-text `searchTerm` + `searchFields`, full `filterByFormula`, or plain list with sort/view/fields
* **Full CRUD + Upsert**: Create, read, update, delete, and batch-upsert records (up to 10 per call — Airtable's API limit)
* **Field Typecasting**: Optional `typecast` flag coerces string values to existing select options, numbers, and dates so agents don't have to format values exactly
* **View-Aware Queries**: Scope results to a named view so the agent honors the same filters your team uses in the UI
* **Offset Pagination**: Seamlessly page through large tables via the `nextOffset` cursor

## Prerequisites

* Active Airtable account (free tier works)
* A **Personal Access Token** (PAT) with the correct scopes and the right bases granted

## Setup Guide

<Steps>
  <Step title="Create a Personal Access Token">
    Go to [airtable.com/create/tokens/new](https://airtable.com/create/tokens/new). Give the token a descriptive name (e.g., "Aster Agents").

    Add these scopes:

    * `data.records:read` — read table records
    * `data.records:write` — create, update, and delete records
    * `schema.bases:read` — discover bases, tables, and field metadata

    Under **Access**, select every base the agent should be able to reach. You can add specific bases now and grant more later by editing the token.

    Copy the generated token — it starts with `pat` and is only shown once.

    <Note>
      PATs are tied to the creating user's permissions. If that user loses access to a base, the token loses access to that base too. For long-lived service use, create the PAT under a dedicated service account.
    </Note>
  </Step>

  <Step title="Enable Airtable Integration">
    In Aster Agents, navigate to **Control Hub > Integrations** and locate the Airtable card. Click **Connect** to begin setup.
  </Step>

  <Step title="Configure Connection">
    Provide your Airtable token:

    * **Personal Access Token**: The `pat` token from Step 1
  </Step>

  <Step title="Add Tools to Your Agent">
    Edit your agent and enable the Airtable tools you need:

    * **Get Airtable Schema** — list bases, or inspect tables and fields inside a base
    * **Search Airtable** — find records with free-text search, formula filters, and sorting
    * **Manage Airtable Records** — create, read, update, upsert, and delete records

    We recommend enabling all three — agents use Get Schema first to discover the `baseId`, `tableIdOrName`, and field names before searching or writing.
  </Step>
</Steps>

## Available Tools

### Get Airtable Schema

Discover the structure of your Airtable workspace:

* **Without a baseId**: returns every base the integration has access to (id, name, permission level)
* **With a baseId**: returns every table in that base with fields (id, name, type, description, select choices) and views

Agents should call this first — they use the returned IDs as input to the other two tools.

### Search Airtable

Query records in a table with three modes:

* **Free-text**: `searchTerm` + `searchFields` — case-insensitive substring match across the listed fields, built via `OR(SEARCH(...))`
* **Formula**: `filterByFormula` — any valid Airtable formula, for AND/OR logic, date math, linked-record filtering, etc.
* **Plain list**: no filter — returns records optionally scoped to a `view`, with sort/fields/maxRecords applied

Supports offset-based pagination. Responses include `nextOffset` when more records are available.

### Manage Airtable Records

Perform CRUD operations:

* **get** — retrieve a single record by ID
* **create** — insert 1–10 records in one call
* **update** — patch specific fields on existing records (requires each record's `id`)
* **upsert** — batch insert-or-update using `fieldsToMergeOn` as the match criteria
* **delete** — remove records by ID (single via `recordId`, or up to 10 via `records[].id`)

Use `typecast: true` when writing human-readable values to select / number / date fields — Airtable will coerce strings to match existing options.

## Security Considerations

* **Grant only the bases you need** — PATs can be scoped to specific bases; avoid "all workspaces" unless the agent genuinely needs it
* **Use minimum scopes** — if the agent only reads, don't grant `data.records:write`
* **Rotate PATs periodically** — Airtable tokens do not expire automatically; treat them like long-lived API keys
* **Use a dedicated service user** — creating the PAT under a shared service account avoids losing access when an individual leaves
* **Monitor token activity** — Airtable's token settings page shows last-used timestamps

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Failed">
    * Verify your token is correct and starts with `pat`
    * Check the token hasn't been revoked in [your Airtable token list](https://airtable.com/create/tokens)
    * Confirm the creating user still has access to the base (PAT permissions inherit from that user)
  </Accordion>

  <Accordion title="Base / Table Not Found">
    * The token must explicitly list the base under **Access** — it's not sufficient for the user to have base access
    * Use `airtable_get_schema` (without a baseId) to see exactly which bases the token can reach
    * `tableIdOrName` accepts either the table ID (starts with `tbl`) or its display name — IDs are more stable against renames
  </Accordion>

  <Accordion title="Rate Limiting">
    * Airtable limits each base to **5 requests per second** per integration
    * The tool surfaces a clear error with the retry-after duration when hit
    * For bulk work, use the batch upsert action with up to 10 records per call rather than single-record creates
  </Accordion>

  <Accordion title="Write Fails on Select Fields">
    * By default, writing a string that doesn't exactly match an existing option fails
    * Pass `typecast: true` to let Airtable coerce the string to an existing option (or create a new one for single/multi-select)
    * For linked records, pass an array of record IDs (not names)
  </Accordion>

  <Accordion title="Formula Errors">
    * Wrap field names in `{}` — e.g., `{Status}='Active'`
    * Escape single quotes in string literals as `\'`
    * Use Airtable's formula playground to validate complex formulas before passing them in
  </Accordion>
</AccordionGroup>

## Related Tools

* [Get Airtable Schema](/tools/airtable_get_schema) - Discover bases, tables, and fields
* [Search Airtable](/tools/airtable_search) - Query records with search, formula, or view filters
* [Manage Airtable Records](/tools/airtable_manage_records) - CRUD + batch upsert on records