When a sync runs

A sync is the only time Kumo.io reads your cloud. Nothing else runs against your accounts between syncs. Syncs start in four ways:

• When you connect a source. The Add a Source wizard starts the first sync for you.
• When you start one. From the web app, the API or the kumo command line.
• When your own tooling starts one. For example, a CI job that calls the API after a deployment.
• On your plan's schedule. Kumo.io syncs each workspace on its own, at your plan's interval:

Self-hosted plans follow the hosted plan of the same name. The interval counts from the end of the workspace's last sync that didn't fail, so a sync you start yourself also resets it. A scheduled sync can begin up to about 10 minutes after the interval ends. Workspaces with no sources, archived workspaces, and workspaces with a sync already running are skipped.

While your account is read-only (a trial, subscription or licence has ended), scheduled syncs stop. Your workspace keeps showing its last snapshot until the account is renewed.

Start a sync in the web app

You can sync a whole workspace, or a single source.

A whole workspace. Open the workspace and select Sync Now in its header, or go to the Activity tab, choose Syncs, and select Start Sync. The Start Workspace Sync dialog syncs every source attached to the workspace and then composes one new snapshot. Select Start Sync; the sync run's page opens so you can watch its progress.

Under Advanced Options you can change the Finalization Policy:

• Accept Partial (the default): compose a snapshot if at least one source succeeded.
• Strict: if any source doesn't succeed, stop without composing a snapshot. Use it when you need all-or-nothing evidence, for example for audits.

A single source. On the workspace's Connections tab, select Sync on the source's row. A source's own page also has a Sync History panel with Sync Now.

A workspace can run one workspace sync at a time. Starting another while one is still running is refused.

Start a sync from the API or the command line

Workspace syncs and source syncs each have an API route. Both answer 202 Accepted with a Location header that points at the run:

POST /v1/accounts/{accountId}/workspaces/{workspaceId}/sync-runs
POST /v1/accounts/{accountId}/workspaces/{workspaceId}/sources/{sourceId}/sync

Starting a workspace sync while another is active returns 409 with the code SYNC_RUN_IN_PROGRESS. The full request and response shapes are in the API reference.

From the command line, sync one source:

kumo source sync --source <source-id>

Against a hosted workspace, pass the source's id and the workspace's id. See the CLI reference.

What happens during a sync

A workspace sync moves through four phases, shown as a progress strip on its Sync Run page:

1. Queued: the run is waiting to start.
2. Syncing sources: Kumo.io reads each source's provider, read-only. The page shows how many sources have synced so far.
3. Composing snapshot: Kumo.io seals the results into a new revision of the workspace.
4. Done: or Failed or Cancelled if the run stopped.

The Sync Log panel streams what each source is doing, and you can filter it by phase and by source. If sources were rejected, the page says how many. Most rejections are credential or permission problems; the log names the failing source.

To stop a run, select Cancel Run. Sources that already finished stay recorded, but a cancelled run composes no snapshot. A run that has started composing its snapshot can no longer be cancelled.

Every run, with its status and duration, is listed under Activity › Runs.

What a sync produces

When a sync succeeds, or partly succeeds under Accept Partial, Kumo.io:

1. Seals a new revision, the snapshot you see across the app. Revisions are kept, so the workspace builds up a timeline. See Revisions and the timeline.
2. Identifies environments from what it found, and re-evaluates your custom environments. See Environments.
3. Generates the default diagrams for each environment.
4. Works out what changed since the previous revision.

You keep working while a sync runs. Screens show the previous result until the new snapshot is ready; environments, for example, are marked Updating with "Sync in progress · showing previous result". If a sync fails or is cancelled, your diagrams keep showing the previous snapshot.

Every sync reads the whole of each source, so each revision is a complete picture rather than a patch on the last one.

How often you can sync

Your plan sets the shortest gap between syncs of a workspace:

The gap counts from the start of the workspace's last workspace sync. A workspace's first sync is always allowed, so connecting a source never waits.

If you start a sync too soon, Kumo.io refuses it with 429 and the code RATE_LIMITED, and the web app shows Rate Limited. The message says how long to wait, for example:

Your plan syncs at most once per 360 min; retry in 3600s.

The full list of plan limits is on Plans and limits.