Airtable

1. Sign in at airtable.com and open the Personal Access Tokens page.
2. Click Create new token.
3. Name it ingest (or similar).
4. Add the scopes: data.records:read, schema.bases:read, and webhook:manage (and optionally user.email:read, so the token-info endpoint can report your email). Read-only scopes are sufficient — Ingest never writes back.
5. Under Access, choose the workspaces and bases you want Ingest to read. You can grant access to all current and future bases in a workspace, or a specific list.
6. Click Create token and copy the value immediately. Airtable only shows the token once.

In the Ingest UI under Connectors → Airtable, paste the token. Ingest stores it in AWS Secrets Manager under the key token.

Airtable enforces a hard rate limit of 5 requests per second per base, with no paid upgrade available. Across all bases on a single token the cap is 50 req/sec. The Ingest runtime is conservative — it dispatches 2 req/sec by default and uses AIMD backoff when it sees a 429. Note that Airtable's 429 response does not include a Retry-After header, so the runtime backs off purely on its own divisor.

Errors with status 401 (bad/expired token), 403 (scope missing or paid feature), 404 (base or table moved/deleted), or 422 (malformed request) are treated as fatal — the request stops without retry.

Most Airtable customers want records (the rows of every table) plus base_schema (the table/field metadata that lets you join records to human-readable column names). The cascade looks like:

• bases — every base the token can see (root)
• base_schema — tables, fields, and views inside each base (per-base)
• records — the actual cell data, one row per record (per-table)
• webhooks — registered webhook subscriptions (optional, per-base)
• whoami — token info: your user ID (and email, if the user.email:read scope is granted). A quick sanity check that the token is valid and can see what you expect.

base_collaborators and base_shares are Business+ paid-tier endpoints and require an upgraded workspace. comments is omitted from the v1 catalog because it fans out one request per record across every table — the design will be revisited once the runtime supports per-record incremental cursors.