Limits & Polling

Per-Call Limits

Enforced server-side. Exceeding a limit fails the call with a descriptive error.

Tool / surface	Limit
Uploaded import file	25 MiB per file (get_upload_url rejects larger)
suggest_column_mapping	200 source columns, 5 sample rows
get_external_ids	500 per page (default 100)
list_imports	100 per page (default 25)

Splitting Large Imports

A single uploaded file can be up to 25 MiB — comfortably tens of thousands of rows. If your dataset is larger, split it into multiple files of up to 25 MiB each and run the get_upload_url → start_csv_import flow once per file. Use the same source value for every file so Adva groups them as one logical import:

file 1: customers-part-1.csv  (source="airtable")
file 2: customers-part-2.csv  (source="airtable")

Each file produces its own import_job_id; poll each independently. Thanks to (source, external_id) idempotency, re-running any single file is safe.

Rate Limits

Auth mode	Limit
API key	10,000 requests/hour per key (default)
OAuth	No separate per-user rate limit

API-key rate limits are configurable per-key; contact Adva if your workload needs a higher ceiling.

Polling an Import Job

Imports are processed asynchronously. After start_csv_import returns an import_job_id, poll get_import_status until the job reaches a terminal state.

Recommended cadence

Job size	Initial poll	Back off to
< 100 rows	Every 2 seconds	Every 5 seconds after 30s
100 - 1000 rows	Every 5 seconds	Every 15 seconds after 1m
Multiple chunks	Poll each job every 10 seconds	Every 30 seconds after 2m

Job lifecycle

pending --> validating --> importing --> completed
                                     \-> failed

• pending — queued, not yet started
• validating — records are being checked against the schema
• importing — valid records are being inserted/updated
• completed — done. Check error_rows and errors[] for per-row problems even when the job itself succeeded.
• failed — the whole job aborted. errors[] explains why.

Typical completion times

• < 100 rows: a few seconds
• 1000 rows: usually under a minute
• Multiple chunked jobs of 1000 each: run in parallel; total time depends on backend concurrency, typically a few minutes for 10K rows

If a job sits in pending for more than 60 seconds or importing for more than 5 minutes, something is likely wrong — check list_imports for any failed jobs that might be blocking progress.