curl --request POST \
--url https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"dest_table": "<string>",
"kb_id": 123,
"source": {
"connection_ref": "<string>",
"table": "<string>",
"kind": "postgres",
"columns": [
"<string>"
],
"cursor_column": "<string>",
"schema": "<string>"
},
"batch_rows": 1,
"cursor": {},
"key_columns": [
"<string>"
],
"mode": "<string>",
"pacing": {
"batch_delay_ms": 1,
"max_dop": 1,
"max_rows_per_sec": 1,
"read_uncommitted": true
},
"placement": "<string>"
}
'import requests
url = "https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs"
payload = {
"dest_table": "<string>",
"kb_id": 123,
"source": {
"connection_ref": "<string>",
"table": "<string>",
"kind": "postgres",
"columns": ["<string>"],
"cursor_column": "<string>",
"schema": "<string>"
},
"batch_rows": 1,
"cursor": {},
"key_columns": ["<string>"],
"mode": "<string>",
"pacing": {
"batch_delay_ms": 1,
"max_dop": 1,
"max_rows_per_sec": 1,
"read_uncommitted": True
},
"placement": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
dest_table: '<string>',
kb_id: 123,
source: {
connection_ref: '<string>',
table: '<string>',
kind: 'postgres',
columns: ['<string>'],
cursor_column: '<string>',
schema: '<string>'
},
batch_rows: 1,
cursor: {},
key_columns: ['<string>'],
mode: '<string>',
pacing: {batch_delay_ms: 1, max_dop: 1, max_rows_per_sec: 1, read_uncommitted: true},
placement: '<string>'
})
};
fetch('https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'dest_table' => '<string>',
'kb_id' => 123,
'source' => [
'connection_ref' => '<string>',
'table' => '<string>',
'kind' => 'postgres',
'columns' => [
'<string>'
],
'cursor_column' => '<string>',
'schema' => '<string>'
],
'batch_rows' => 1,
'cursor' => [
],
'key_columns' => [
'<string>'
],
'mode' => '<string>',
'pacing' => [
'batch_delay_ms' => 1,
'max_dop' => 1,
'max_rows_per_sec' => 1,
'read_uncommitted' => true
],
'placement' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs"
payload := strings.NewReader("{\n \"dest_table\": \"<string>\",\n \"kb_id\": 123,\n \"source\": {\n \"connection_ref\": \"<string>\",\n \"table\": \"<string>\",\n \"kind\": \"postgres\",\n \"columns\": [\n \"<string>\"\n ],\n \"cursor_column\": \"<string>\",\n \"schema\": \"<string>\"\n },\n \"batch_rows\": 1,\n \"cursor\": {},\n \"key_columns\": [\n \"<string>\"\n ],\n \"mode\": \"<string>\",\n \"pacing\": {\n \"batch_delay_ms\": 1,\n \"max_dop\": 1,\n \"max_rows_per_sec\": 1,\n \"read_uncommitted\": true\n },\n \"placement\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"dest_table\": \"<string>\",\n \"kb_id\": 123,\n \"source\": {\n \"connection_ref\": \"<string>\",\n \"table\": \"<string>\",\n \"kind\": \"postgres\",\n \"columns\": [\n \"<string>\"\n ],\n \"cursor_column\": \"<string>\",\n \"schema\": \"<string>\"\n },\n \"batch_rows\": 1,\n \"cursor\": {},\n \"key_columns\": [\n \"<string>\"\n ],\n \"mode\": \"<string>\",\n \"pacing\": {\n \"batch_delay_ms\": 1,\n \"max_dop\": 1,\n \"max_rows_per_sec\": 1,\n \"read_uncommitted\": true\n },\n \"placement\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"dest_table\": \"<string>\",\n \"kb_id\": 123,\n \"source\": {\n \"connection_ref\": \"<string>\",\n \"table\": \"<string>\",\n \"kind\": \"postgres\",\n \"columns\": [\n \"<string>\"\n ],\n \"cursor_column\": \"<string>\",\n \"schema\": \"<string>\"\n },\n \"batch_rows\": 1,\n \"cursor\": {},\n \"key_columns\": [\n \"<string>\"\n ],\n \"mode\": \"<string>\",\n \"pacing\": {\n \"batch_delay_ms\": 1,\n \"max_dop\": 1,\n \"max_rows_per_sec\": 1,\n \"read_uncommitted\": true\n },\n \"placement\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>"
}Create Connector Job
Dispatch a job to a connector.
curl --request POST \
--url https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"dest_table": "<string>",
"kb_id": 123,
"source": {
"connection_ref": "<string>",
"table": "<string>",
"kind": "postgres",
"columns": [
"<string>"
],
"cursor_column": "<string>",
"schema": "<string>"
},
"batch_rows": 1,
"cursor": {},
"key_columns": [
"<string>"
],
"mode": "<string>",
"pacing": {
"batch_delay_ms": 1,
"max_dop": 1,
"max_rows_per_sec": 1,
"read_uncommitted": true
},
"placement": "<string>"
}
'import requests
url = "https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs"
payload = {
"dest_table": "<string>",
"kb_id": 123,
"source": {
"connection_ref": "<string>",
"table": "<string>",
"kind": "postgres",
"columns": ["<string>"],
"cursor_column": "<string>",
"schema": "<string>"
},
"batch_rows": 1,
"cursor": {},
"key_columns": ["<string>"],
"mode": "<string>",
"pacing": {
"batch_delay_ms": 1,
"max_dop": 1,
"max_rows_per_sec": 1,
"read_uncommitted": True
},
"placement": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
dest_table: '<string>',
kb_id: 123,
source: {
connection_ref: '<string>',
table: '<string>',
kind: 'postgres',
columns: ['<string>'],
cursor_column: '<string>',
schema: '<string>'
},
batch_rows: 1,
cursor: {},
key_columns: ['<string>'],
mode: '<string>',
pacing: {batch_delay_ms: 1, max_dop: 1, max_rows_per_sec: 1, read_uncommitted: true},
placement: '<string>'
})
};
fetch('https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'dest_table' => '<string>',
'kb_id' => 123,
'source' => [
'connection_ref' => '<string>',
'table' => '<string>',
'kind' => 'postgres',
'columns' => [
'<string>'
],
'cursor_column' => '<string>',
'schema' => '<string>'
],
'batch_rows' => 1,
'cursor' => [
],
'key_columns' => [
'<string>'
],
'mode' => '<string>',
'pacing' => [
'batch_delay_ms' => 1,
'max_dop' => 1,
'max_rows_per_sec' => 1,
'read_uncommitted' => true
],
'placement' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs"
payload := strings.NewReader("{\n \"dest_table\": \"<string>\",\n \"kb_id\": 123,\n \"source\": {\n \"connection_ref\": \"<string>\",\n \"table\": \"<string>\",\n \"kind\": \"postgres\",\n \"columns\": [\n \"<string>\"\n ],\n \"cursor_column\": \"<string>\",\n \"schema\": \"<string>\"\n },\n \"batch_rows\": 1,\n \"cursor\": {},\n \"key_columns\": [\n \"<string>\"\n ],\n \"mode\": \"<string>\",\n \"pacing\": {\n \"batch_delay_ms\": 1,\n \"max_dop\": 1,\n \"max_rows_per_sec\": 1,\n \"read_uncommitted\": true\n },\n \"placement\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"dest_table\": \"<string>\",\n \"kb_id\": 123,\n \"source\": {\n \"connection_ref\": \"<string>\",\n \"table\": \"<string>\",\n \"kind\": \"postgres\",\n \"columns\": [\n \"<string>\"\n ],\n \"cursor_column\": \"<string>\",\n \"schema\": \"<string>\"\n },\n \"batch_rows\": 1,\n \"cursor\": {},\n \"key_columns\": [\n \"<string>\"\n ],\n \"mode\": \"<string>\",\n \"pacing\": {\n \"batch_delay_ms\": 1,\n \"max_dop\": 1,\n \"max_rows_per_sec\": 1,\n \"read_uncommitted\": true\n },\n \"placement\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.timbal.ai/orgs/{org_id}/connectors/{connector_id}/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"dest_table\": \"<string>\",\n \"kb_id\": 123,\n \"source\": {\n \"connection_ref\": \"<string>\",\n \"table\": \"<string>\",\n \"kind\": \"postgres\",\n \"columns\": [\n \"<string>\"\n ],\n \"cursor_column\": \"<string>\",\n \"schema\": \"<string>\"\n },\n \"batch_rows\": 1,\n \"cursor\": {},\n \"key_columns\": [\n \"<string>\"\n ],\n \"mode\": \"<string>\",\n \"pacing\": {\n \"batch_delay_ms\": 1,\n \"max_dop\": 1,\n \"max_rows_per_sec\": 1,\n \"read_uncommitted\": true\n },\n \"placement\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>"
}Authorizations
Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.
Body
Destination table inside the KB.
Target KB (numeric id, same as the /k2 routes).
The source half of a dispatch, tagged by kind. Each variant maps to a
SourceSpec and gates on the connector advertising the matching
source:<kind> capability. Request shape:
"source": { "kind": "sql_server", "connection_ref": "...", "table": "...", "cursor_column": "..." }.
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Target rows per batch. Defaults to 5000.
x >= 0Resume checkpoint; omit for a full initial extract.
Ordered destination PRIMARY KEY columns. Omit for a keyless table.
Honored when the run builds the table (create/replace). Key columns
are auto-added to a source.columns subset, so they only need to exist
on the source table. Source these from the browse columns' pk_position
for a faithful copy of the source key.
create | append | replace | upsert. Defaults to create.
upsert merges each batch on key_columns (rows with an existing key are
overwritten, new keys inserted); requires non-empty key_columns. If the
destination table doesn't exist yet, the first upsert builds it keyed.
Optional load-shaping for gentle extraction against busy source systems. Omit for no throttle.
Show child attributes
Show child attributes
Where the KB's data lives: hosted (control-plane KB, the default) or
local (a KB runtime inside the connector's environment — requires the
connector to advertise the kb:local capability).
Response
Job accepted and dispatched