# syncEvents (https://www.cal-sdk.com/docs/reference/sync-events)

Use `syncEvents` to keep a local copy of a calendar, such as a table in Postgres, up to date. The first call returns what the provider syncs, and each later call returns what changed since the cursor you pass. Save the new cursor after applying the changes. [Sync changes](/docs/guides/sync#how-each-provider-syncs) covers how much each provider fetches, and Outlook's fixed window.

```ts
import { syncEvents } from '@cal-sdk/core';

const { changes, nextCursor } = await syncEvents({ calendar, cursor: stored });
for (const change of changes) await apply(change);
await saveCursor(nextCursor);
```

## Options [#options]

<TypeTable
  type={{
    cursor: { type: 'string', description: '`nextCursor` from the previous sync. Leave out for a full first sync.' },
    calendarId: { type: 'string', default: "'primary'" },
    paginate: { type: 'boolean', description: '`false` returns one page at a time.', default: 'true' },
    pageToken: { type: 'string', description: 'With `paginate: false`, `nextPageToken` from the previous page of this round.' },
  }}
/>

Plus the [common options](/docs/reference#common-options).

## Result [#result]

<TypeTable
  type={{
    changes: { type: "({ type: 'upsert'; event: CalendarEvent } | { type: 'delete'; eventId: string })[]", description: 'Every change since `cursor`, in the order the provider returns them. Apply them in that order.', required: true },
    nextCursor: { type: 'string', description: 'Store it and pass it as `cursor` next time. Always present by default. With `paginate: false`, only on the last page.' },
    nextPageToken: { type: 'string', description: 'With `paginate: false`: more pages are left in this round.' },
    warnings: { type: 'Warning[]', required: true },
  }}
/>

Changes cover single events, series and exceptions, never computed occurrences.

## Throws [#throws]

- `SyncCursorExpiredError` when the provider no longer accepts the cursor. Drop it, and your copy, and sync without one.
- `UnsupportedFunctionalityError` when the provider has no sync. Every built-in provider has it.