sync-connector

• sync_id: the sync to pass to get-connector-sync.
• connector_id: the connector you named.
• joined: true when a running sync was joined, false when this call started one.
• status: always running: the sync has just started, or is still running.

A real response, captured from a live call to sync-connector that started a sync of a Linear connector. Nothing is changed.

{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000002\",\"result\":{\"sync_id\":\"connector-sync-6aa9beb7ec8121a43b6c791b-6ab3608bf19beb4f0ed39e77-1790280549835063253\",\"connector_id\":\"6ab3608bf19beb4f0ed39e77\",\"joined\":false,\"status\":\"running\"}}"
    }
  ],
  "isError": false
}

{
  "lifecycle_id": "qlc_000002",
  "result": {
    "sync_id": "connector-sync-6aa9beb7ec8121a43b6c791b-6ab3608bf19beb4f0ed39e77-1790280549835063253",
    "connector_id": "6ab3608bf19beb4f0ed39e77",
    "joined": false,
    "status": "running"
  }
}

// the object you get back IS the result — there is no `.result` to read
{
  "sync_id": "connector-sync-6aa9beb7ec8121a43b6c791b-6ab3608bf19beb4f0ed39e77-1790280549835063253",
  "connector_id": "6ab3608bf19beb4f0ed39e77",
  "joined": false,
  "status": "running"
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000002'

# a dict subclass; `result` is already unwrapped
{
 "sync_id": "connector-sync-6aa9beb7ec8121a43b6c791b-6ab3608bf19beb4f0ed39e77-1790280549835063253",
 "connector_id": "6ab3608bf19beb4f0ed39e77",
 "joined": False,
 "status": "running"
}

out.lifecycle_id  # 'qlc_000002' — an attribute, not a key

A sync can run for minutes, so the call never waits for it. Pass the sync_id to get-connector-sync to follow it, or let an SDK wait for you. See ingestion for following the result.

Both SDKs take three options that are not sent to the platform:

• wait (Python and TypeScript, default off): poll get-connector-sync until the sync is no longer running.
• wait_timeout in Python, waitTimeout in TypeScript (default 600): the most seconds to wait.
• poll (default 5): seconds between two polls.

With wait, both SDKs start or join the sync, then poll until its status is no longer running, and return that last status with joined added. A failed sync comes back as a status with status: "failed"; it is not raised. wait waits only for the refresh of the connector's actions and ontology. It never waits for ingestion to finish, because a native connector such as Linear or Slack cannot report when its data is all in: read the ingestion field of the status for what is known. When the time limit is reached, the SDK stops polling and returns the last status, which still says status: "running". Nothing is raised, and the sync goes on.

sync = fabric.sync_connector(connector_id="6ab3608bf19beb4f0ed39e77", wait=True)

In the console, the Connectors page has two buttons for refreshing. Sync to Context at the top syncs all of the project's connectors. Sync this connector, in the menu on one connector's card, does what this tool does. Sync frequency in the same menu sets how often that connector is polled after its first full sync, within the range the dialog shows.

You can sync a connector when list-connectors shows it to you, which the access scope chosen at provisioning decides (the same rule that decides which actions you can run), and it was provisioned in your project. A connector provisioned in another project is refused, even when its access scope lets you use its actions.

By access scope, it is listed for you when:

• organization: your project is in the connector's organization.
• department: your project is in the connector's department.
• project: your project is the project the connector was provisioned in.
• individual: you are the person who provisioned it.

A connector in another organization is always refused. Every refusal is the same S8:connector-not-usable error, so the answer does not tell you whether a connector you cannot use exists.

When a sync of the connector is still running, the call does not start a second one. It answers with the id of the running sync and joined: true, so the load on the connected system never doubles. A finished sync is not joined: the next call starts a new one. Two calls in the same instant can both start a sync, because neither sees the other yet. The console's own Sync button always starts a new sync.

Every call writes a sync-connector.run audit event, whether it started a sync, joined one or was refused: who called, the connector, its access scope and department, your department, the sync_id, and the outcome (started, joined, refused or failed). A call refused because the credential lacks the grant is recorded as sync-connector.rejected.

Not marked consequential, so it does not wait for approval: a sync only reads from the connected system, and scheduled automation must be able to run it. A sync reads the connected system with the connector's own credential and can pull all of its data into your project's context graph. That is why it needs its own grant, and why a key that may run actions or read data does not gain it. Administrator keys carry it by default. An API key minted before the grant existed does not carry it, and must be reissued to use this tool.