Authorization: Bearer $API_KEY, and the ConnectorsManage role for anything that dispatches work.
The commands below use
$ORG_ID, $CONNECTOR_ID (from GET /orgs/$ORG_ID/connectors) and $KB_ID. They run against Timbal’s API, not on the server. All paths are under https://api.timbal.ai/orgs/$ORG_ID/connectors/$CONNECTOR_ID.
Find what to sync
1
List the connections
Only the names you configured on the server come back.
2
List the tables
approx_rows: -1 means the database has never analyzed the table.3
Read the columns
cursor_candidate) and its place in the primary key (pk_position, starting at 1). Those two fields are everything you need to configure a sync.4
Inspect one table in depth (optional)
Adds indexes, foreign keys, check constraints, comments and size. Needs connector 0.1.25.
doctor --connection erp --table dbo.Cust_Ledger_Entry gives the same answer on the server, without a live connection to Timbal. These calls time out after 15 seconds.
Try a query
Run one statement and see the result, to check a table before syncing it. It needs the ConnectorsManage role, connector 0.1.26 or newer, and the connection’squery setting to allow it, and every run is recorded in the audit log.
On MySQL and MariaDB send one statement. On PostgreSQL and SQL Server you can send several and get the last result set back (on PostgreSQL the last one that returns rows; SQL Server returns the true last set, even if empty).
rows_affected counts changed rows for statements that return none on PostgreSQL and MySQL, and is null on SQL Server. See Run an ad-hoc query.
One-off job
A job copies a table once, starting now.source.kind is postgres, sql_server or mysql. List recent jobs with GET /orgs/$ORG_ID/connectors/jobs?connector_id=$CONNECTOR_ID and stop one with POST .../jobs/$JOB_ID/stop. Stopping returns 200 { "job_id", "state" } and is safe to repeat. A job goes accepted, running, then completed, failed or stopped, and a finished job stays finished.
Other fields:
columns (a subset of columns; key_columns are added to it automatically), batch_rows (default 5000), and pacing to protect a busy source: batch_delay_ms and max_rows_per_sec (any source), max_dop and read_uncommitted (SQL Server only). See Create job.
Start from a point
cursor is an inclusive lower bound on the cursor column. It works with every mode: create a table with only the rows from a date on, or resume after a previous run.
A table with no usable cursor
Leave outcursor_column and the job does one full scan, with no checkpoint: if it stops or fails, it starts over. Use it when nothing is monotonic, the only candidates are nullable, or a non-unique candidate has no primary key to break ties. Needs connector 0.1.25, and cursor can’t be set.
Scheduled sync
A sync stores the definition and runs it on an interval. Each run continues from where the last one landed.- The first run builds
dest_table. Later runs append, or merge whenkey_columnsis set. start_cursoris a floor for the first run only.interval_secsis the time between run starts, with a floor of about 30 seconds (any whole number of seconds up to 2147483647).- The sync is created, not run: wait for the next tick, or run it now.
- List the syncs of a connector with
GET /orgs/$ORG_ID/connectors/syncs?connector_id=$CONNECTOR_ID.
Adopt a table you already loaded
The usual path from “I copied these tables with one-off jobs” to “keep them fresh”: create the sync against the samedest_table. By default (existing_dest: "adopt") Timbal reads the largest cursor value in the table and continues from there, instead of loading it again.
key_columns you pass must match the table’s own primary key. Pass initial_cursor if the derived value is wrong (for example a job you stopped halfway), or existing_dest: "replace" to throw the table away and rebuild it. start_cursor is ignored when adopting, initial_cursor without an existing table is a 400, and an adopted table that is empty is simply built.
Run now
sync_disabled) and have no run in progress (run_active; stop the job first). Needs connector 0.1.30.
Pause, change, delete
PATCH and DELETE answer 204. PATCH only takes enabled and interval_secs. To change the source or destination, delete the sync and create it again against the same dest_table: it adopts the rows already there.
Full-refresh sync
Leave outsource.cursor_column and the sync is no longer incremental: every run reads the whole table and rebuilds dest_table. Use it for tables that are updated or deleted in place with nothing recording it. An incremental sync would keep appending and never notice a deletion.
- The whole table crosses the connection every
interval_secs. Size the interval to the table, and prefer an incremental sync whenever there is a usable cursor. - While it runs, the destination is rebuilt in place: a query at that moment sees a partial table, and a run that fails halfway leaves one until the next run completes.
- If the source is emptied, the destination is emptied too.
start_cursor,initial_cursorandexisting_dest: "adopt"are refused: there is nowhere to continue from.existing_dest: "replace"is accepted and changes nothing.key_columnskeep the primary key on each rebuild, andpacinghelps with large tables. Needs connector 0.1.25.
Keys and merging
key_columns are the destination’s primary key, in order. Take them from pk_position in the column list.
- With keys, the first run creates a keyed table and later runs merge: a row that comes again overwrites its previous version.
- Without keys, the table is append-only.
upsertneeds keys. They’re also strongly recommended whenever the cursor isn’t unique on its own.
Choosing a cursor
The connector reads in batches, ordered by the cursor and then the key, and remembers the last row it landed.
Every run after the first resumes inclusively from the saved checkpoint. It first removes the rows at or after it (for a keyset cursor, the exact matching row), then reads again from it, so a crash or restart never leaves duplicates. Keyed tables merge on every batch anyway.
Dates and times are converted to what the column’s type accepts: fractions of a second are trimmed to the type’s precision, and time-zone suffixes are removed where the type can’t hold them. That means an ISO value such as
2026-06-01T00:00:00Z works as a floor on every database. Connector 0.1.24 or newer: older versions failed on legacy datetime columns in SQL Server, and silently matched no rows on MySQL.
Watch a sync
Failures back off. A run that fails itself (a source SQL error, not a disconnect or a stop) doubles the wait before the next try, up to an hour or the interval, whichever is larger. After 10 failures in a row the sync is disabled and
disabled_reason says why. A completed run resets the count, and so does enabling the sync again. Fix the cause, then PATCH {"enabled": true} (this also clears disabled_reason) and run it now. Trying to run a disabled sync returns sync_disabled with the reason.
Common refusals
Next steps
File shares in Timbal
Explore folders and copy files into a knowledge base.
Connect your IDE
Browse schemas and run bounded SQL from Cursor.