Airtable Source

Connect Airtable as a source to sync bases, tables, and records from your Airtable workspace into your data warehouse.

For an overview of capabilities and use cases, see the Airtable connector page. To run pipelines natively inside Snowflake, see Snowflake Native ETL.

Prerequisites

Before you begin, ensure you have:

• ✅ An active Airtable account
• ✅ For OAuth: Admin access to Airtable bases you want to sync
• ✅ For Personal Access Token: Ability to create tokens at airtable.com/create/tokens
• ✅ Required scopes: data.records:read, schema.bases:read

What Gets Synced

Supaflow discovers all bases and tables that the authenticated user (or token) has access to. Each Airtable table becomes a table in your destination.

Sync mode: Full refresh. All records are fetched on each sync. Airtable's API does not support filtered queries by modification date, so incremental sync is not available.

Field Type Mapping

Airtable field types are mapped to destination column types automatically:

Airtable Field Type	Destination Type	Notes
Single line text, Long text, URL, Email, Phone	STRING
Number, Currency, Percent	DOUBLE or BIGDECIMAL	Based on precision
Checkbox	BOOLEAN
Date, Date and time	TIMESTAMP
Single select	STRING	Option name as text
Multiple select	JSON ARRAY	Array of option names
Linked records	JSON ARRAY	Array of linked record IDs
Attachments	JSON ARRAY	Array of attachment objects (URL, filename, size)
Formula, Rollup, Count, Lookup	Varies	Mapped based on the formula's result type
Auto number	LONG
Created time, Last modified time	TIMESTAMP
Created by, Last modified by	JSON	User object with email and name

Rate Limiting

Airtable enforces a rate limit of 5 requests per second per base. Supaflow respects this limit automatically with built-in backoff and retry logic. For workspaces with many tables:

• Large tables (100,000+ records) may take longer to sync since records are fetched in pages of 100
• Multiple bases can be synced in parallel since rate limits are per-base
• If you hit rate limits from other integrations, consider scheduling Supaflow syncs during off-peak hours

Configuration

Step 1: Choose Authentication Method

Authentication Method*

Select your authentication method
Options:

• oauth (Recommended) - Easy browser-based authentication
• personal_access_token - Server-to-server authentication with static token

Default: oauth

---

Option A: OAuth Authentication (Recommended)

Click Authorize to connect to your Airtable account using OAuth. This method:

• Provides easy browser-based authentication
• Automatically manages token refresh
• Requires no manual token creation

Steps:

1. Click the Authorize button
2. Log in to your Airtable account
3. Grant Supaflow access to your bases
4. You'll be redirected back to Supaflow

Required Scopes

OAuth automatically requests the required scopes:

• data.records:read - Read records from tables
• schema.bases:read - Read base and table metadata

---

Option B: Personal Access Token

Personal Access Token*

Airtable Personal Access Token from airtable.com/create/tokens
Required scopes: data.records:read, schema.bases:read
Stored encrypted

How to create a Personal Access Token:

1. Go to airtable.com/create/tokens
2. Click Create new token
3. Give it a descriptive name (e.g., "Supaflow Integration")
4. Add scopes:
   • data.records:read
   • schema.bases:read
5. Add access to specific bases you want to sync
6. Click Create token
7. Copy the token (starts with "pat...")
8. Paste it into the Personal Access Token field

Token Security

Personal Access Tokens are stored encrypted in Supaflow and never exposed in logs or UI.

---

Step 2: Advanced Settings (Optional)

Schema Refresh Interval

Interval in minutes for schema metadata refresh
Default: 60
Range: -1 to 10080

Options:

• 0 = Refresh before every pipeline execution (most accurate, slower)
• 60 = Refresh every hour (recommended)
• -1 = Disable schema refresh (use with caution)

When to Adjust Schema Refresh

• Set to 0 if you frequently add/remove fields in Airtable
• Set to higher values (e.g., 1440 for daily) if your schema is stable
• Setting to -1 will use cached schema indefinitely - only use if schema never changes

---

Step 3: Test & Save

After configuring your authentication method, click Test & Save to verify your connection and save the source.

Troubleshooting

Common issues and their solutions:

OAuth authorization failed

Problem:

• Cannot complete OAuth flow
• "Access denied" error
• Redirect fails after clicking Authorize

Solutions:

1. Check browser settings:
   • Disable popup blockers for Supaflow
   • Allow third-party cookies
   • Try in incognito/private mode
2. Verify account access:
   • Ensure you have access to at least one Airtable base
   • Check if your organization allows OAuth apps
3. Clear cache and retry:
   • Clear browser cookies and cache
   • Try different browser (Chrome, Firefox, Edge)
4. Reconnect:
   • Delete the source and create a new one
   • Complete OAuth flow again

---

Personal Access Token authentication failed

Problem:

• "Invalid credentials" error
• "Authentication failed" message
• Connection test fails

Solutions:

1. Verify token is valid:
   • Check token hasn't expired or been revoked
   • Go to airtable.com/create/tokens to verify
2. Check token scopes:
   • Token must have data.records:read
   • Token must have schema.bases:read
   • Edit token in Airtable to add missing scopes
3. Verify base access:
   • Token must have access to at least one base
   • Add specific bases in token configuration
4. Copy token correctly:
   • Token should start with "pat..."
   • No extra spaces before/after
   • Copy the entire token

---

No bases appearing

Problem:

• Successfully connected but no bases show up
• Schema is empty
• "No Airtable bases found" warning

Solutions:

1. For OAuth:
   • Reconnect and ensure you grant access during authorization
   • Check if your account has access to any bases
   • Verify you're logged into the correct Airtable account
2. For Personal Access Token:
   • Verify token has schema.bases:read scope
   • Add specific bases to token access list at airtable.com/create/tokens
   • Check if bases exist in your workspace
3. Check permissions:
   • Ensure you have at least read access to bases
   • Verify bases haven't been deleted or moved
4. Refresh schema:
   • Set Schema Refresh Interval to 0
   • Save and test connection again

---

Missing tables or fields

Problem:

• Some tables don't appear in schema
• Fields are missing from tables
• Recently added fields not visible

Solutions:

1. Refresh schema:
   • Set Schema Refresh Interval to 0 (force refresh)
   • Save and test connection
   • Wait a few minutes for schema to sync
2. Check permissions:
   • Verify you have read access to the table
   • Check field-level permissions
   • Ensure fields aren't hidden in Airtable
3. Verify table exists:
   • Confirm table hasn't been deleted or renamed
   • Check if table is in a different base
4. For new fields:
   • Schema refresh needed after adding fields
   • Set Schema Refresh Interval to 0 temporarily
   • Or wait for next scheduled refresh

---

Rate limit exceeded

Problem:

• "Rate limit exceeded" error
• "429 Too Many Requests" error
• Sync stops mid-process

Solutions:

1. Airtable rate limits:
   • Free/Plus: 5 requests/second per base
   • Pro/Enterprise: Higher limits
   • Connector automatically retries with backoff
2. Reduce sync frequency:
   • Schedule syncs during off-peak hours
   • Reduce number of tables synced simultaneously
3. Check for other integrations:
   • Multiple apps accessing same base count toward limit
   • Coordinate sync schedules if multiple tools used
4. Upgrade Airtable plan:
   • Higher tier plans have higher rate limits
   • Consider Pro or Enterprise for heavy usage

---

Incremental sync not working

Problem:

• Full refresh happens every time
• "Does not support incremental sync" message
• All records synced instead of just new/updated

Solutions:

1. Add lastModifiedTime field:
   • Airtable tables need a lastModifiedTime field type for incremental sync
   • In Airtable, add a new field with type "Last modified time"
   • Refresh schema in Supaflow (set Schema Refresh Interval to 0)
2. Verify cursor field:
   • Check if lastModifiedTime field appears in Supaflow schema
   • Ensure field is selected as cursor field in pipeline config
3. For append-only tables:
   • If you only insert (never update), you can use createdTime field
   • Manually select _airtable_created_time as cursor field
4. Schema refresh required:
   • After adding lastModifiedTime field in Airtable
   • Set Schema Refresh Interval to 0 and save
   • Field should appear in next schema discovery

---

Connection timeout

Problem:

• Connection times out during setup
• Slow response from Airtable
• Test connection takes too long

Solutions:

1. Check Airtable status:
   • Visit: Airtable Status Page
   • Verify if Airtable is experiencing issues
2. Network connectivity:
   • Verify internet connection is stable
   • Check if corporate firewall blocks Airtable
3. Retry later:
   • Airtable may be experiencing high load
   • Try during off-peak hours
4. Reduce base size:
   • Large bases with many tables take longer
   • Consider breaking into smaller bases if possible

---

OAuth token expired

Problem:

• Sync worked before but now fails
• "Invalid OAuth credentials" error
• Token expiration warnings

Solutions:

1. Automatic refresh:
   • OAuth tokens automatically refresh (1 hour expiry)
   • Framework handles token refresh transparently
2. If auto-refresh fails:
   • Reconnect via OAuth
   • Delete source and create new one
   • Complete OAuth authorization again
3. Check refresh token:
   • Refresh token must be valid
   • If revoked, full re-authorization needed
4. Verify integration still allowed:
   • Check if Airtable integration was disabled
   • Ensure Supaflow app is still authorized

Support

Need help? Contact us at support@supa-flow.io