Skip to main content

Managing Sync State (Cursors)

Saddle Data uses Cursors to track the progress of incremental syncs. A cursor is typically a timestamp (like updated_at) or an incrementing ID that tells the system where the last sync left off.

To provide full transparency and control, Saddle Data makes these cursors visible and editable via both the UI and the API.

Viewing Cursors​

You can view the current sync state for any flow:

  1. Navigate to the Flow Detail page.
  2. Click on the "Sync State (Cursors)" tab.
  3. You will see a table listing each entity (table) in the flow, its current cursor value, and when it was last updated.

Manual Overrides​

Sometimes you may need to manually adjust a cursor to "rewind" or "fast-forward" a sync.

Rewinding a Sync​

If you've fixed a bug in a transformation and want to re-process data from a certain date:

  1. Find the entity in the Sync State table.
  2. Click the Edit (pencil) icon.
  3. Enter an earlier timestamp (e.g., 2026-01-01T00:00:00Z).
  4. The next time the flow runs, it will pick up all records modified since that date.

Resetting a Cursor​

To perform a full re-sync of a specific entity without truncating the destination table:

  1. Click the Reset (restart) icon next to the entity.
  2. This clears the stored cursor.
  3. The next sync will process all available data from the source for that entity.

API Management​

You can also manage cursors programmatically using the API. This is useful for automated recovery scripts.

Fetch State​

GET /v1/organizations/:orgId/flows/:flowId/state

Update Cursor​

PUT /v1/organizations/:orgId/flows/:flowId/state/:entity

{
  "cursor_value": "2026-03-16T12:00:00Z"
}

Reset Cursor​

DELETE /v1/organizations/:orgId/flows/:flowId/state/:entity

Audit Logging​

Every manual change to a cursor is recorded in the Audit Log. This ensures accountability and helps debug why a sync might have re-processed or skipped data. The log entry includes the entity name and the old/new cursor values.