airtable_batch_upsert
Bulk insert or update up to thousands of Airtable records with automatic chunking and rate-limit backoff. Use for CSV imports, webhooks, and external system syncs.
Instructions
Ingests or bulk-inserts records into an Airtable table using the REST API with automatic 10-record chunking and 5 req/sec rate limit backoff.
When to Use
When bulk-importing rows of data from CSVs, webhooks, or external systems into an Airtable table.
When creating multiple records in batches of 10 to 1,000+ rows efficiently without manual loop management.
When inserting structured data where string values for singleSelect or record links should be auto-cast.
When NOT to Use
Do NOT use this tool to update or delete a single record by record ID. Use 'airtable_manage_records' instead.
Do NOT use this tool for reading or filtering existing records. Use 'airtable_query_records' instead.
Do NOT use this tool to create new tables or modify field schemas. Use 'airtable_create_base_schema' or 'airtable_modify_schema' instead.
Operational Disclosures
Side Effects: Creates new persistent records in the target table. Does not overwrite existing rows unless fields match Airtable's native upsert performUpsert criteria.
Persistence & Idempotency: Additive mutation. Calling multiple times with identical records will create duplicate records unless an external primary key is deduplicated beforehand.
Rate Limiting: Airtable enforces a strict 5 req/sec limit. This tool chunks records into 10-item payloads and sleeps 210ms between requests, with exponential backoff on HTTP 429.
Auth Scopes: Requires Personal Access Token with 'data.records:write' scope.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base_id | Yes | Airtable Base ID (starts with app, e.g. appoorUuG6wgx8dJ1) | |
| records | Yes | Array of record objects mapping field names to values, e.g. [{"Merchant Name": "Acme", "Stage": "Onboarding"}] | |
| typecast | No | When true, automatically creates new select options or converts string values to linked record arrays (default: true) | |
| table_name_or_id | Yes | Target Table Name (e.g. "Merchants", "Orders") or Table ID (starts with tbl) |