Syncs API - Nango

Syncs are TypeScript functions that run on a schedule and cache external API data in Nango. Use the Syncs API to read records, trigger one-off runs, pause and resume schedules, and manage sync variants.

All requests must include an Authorization: Bearer <secret-key> header. See Authentication for details.

Records

List records

GET /records Returns cached records for a connection and model, ordered by modification date ascending. Use cursor-based pagination to retrieve large datasets.

Records not updated for 30 days have their payload pruned (metadata only remains). Records from syncs not run for 60 days are permanently deleted. Fetch and store records in your own system promptly.

Headers

string

required

Bearer <secret-key>

string

required

The ID of the connection to fetch records for.

string

required

The integration ID (unique key) for the connection.

Query parameters

string

required

The name of the sync model to fetch records for, as defined in nango.yaml.

string

The sync variant to fetch records for. Omit to fetch records from the default (base) variant.

string

ISO 8601 timestamp. Only return records modified after this date. Useful for incremental fetches.

string

Filter records by last action. Accepted values: added, updated, deleted, or a comma-separated combination such as added,updated.

string

Pagination cursor from the previous response’s next_cursor field.

number

default:"100"

Maximum number of records to return per page. Maximum value is 500.

string[]

Filter to specific record IDs. Can be specified multiple times: ids=id1&ids=id2.

Response

object[]

required

Array of records matching the query.

Show record properties

any

required

The record’s primary identifier, as defined by the sync model.

any

All other fields as defined in your sync model.

object

required

Nango-managed metadata for this record.

Show properties

string

required

The last operation applied to this record: ADDED, UPDATED, or DELETED.

string

required

ISO 8601 timestamp when this record was first synced.

string

required

ISO 8601 timestamp of the most recent change to this record.

string | null

required

ISO 8601 timestamp when the record was deleted, or null if it is still active.

string

required

Opaque cursor value for this record. Use as the pagination cursor parameter in subsequent requests.

string | null

required

Cursor to pass in the next request to retrieve the following page. null when there are no more records.

curl -X GET "https://api.nango.dev/records?model=GithubIssue&limit=50" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Connection-Id: user-123" \
  -H "Provider-Config-Key: github"

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: process.env['NANGO_SECRET_KEY'] });

const { records, next_cursor } = await nango.listRecords<GithubIssue>({
  providerConfigKey: 'github',
  connectionId: 'user-123',
  model: 'GithubIssue',
  limit: 50
});

Response

{
  "records": [
    {
      "id": 1234567,
      "title": "Fix authentication bug",
      "state": "open",
      "created_at": "2024-01-15T10:30:00Z",
      "_nango_metadata": {
        "last_action": "ADDED",
        "first_seen_at": "2024-01-15T10:31:00.000Z",
        "last_modified_at": "2024-01-15T10:31:00.000Z",
        "deleted_at": null,
        "cursor": "MjAyNC0wMS0xNVQxMDozMTowMC4wMDBafHwxMjM0NTY3"
      }
    }
  ],
  "next_cursor": "MjAyNC0wMS0xNVQxMDozMTowMC4wMDBafHwxMjM0NTY3"
}

Node SDK signature

listRecords<T extends Record<string, any> = Record<string, any>>(
  config: ListRecordsRequestConfig
): Promise<{ records: NangoRecord<T>[]; next_cursor: string | null }>

interface ListRecordsRequestConfig {
  providerConfigKey: string;
  connectionId: string;
  model: string;
  variant?: string;
  modifiedAfter?: string;   // ISO 8601
  limit?: number;
  filter?: 'added' | 'updated' | 'deleted' | 'added,updated' | 'added,deleted' | 'updated,deleted';
  cursor?: string | null;
  ids?: string[];
}

Prune records

PATCH /records/prune Empties the payload for records up to a specified cursor, while preserving record metadata. Use this to meet compliance requirements without losing the ability to track record state. The payload can be restored by re-syncing.

Pruning only affects Nango’s cache. It does not delete anything on the external API and is not the same as detecting a deletion from the source.

Headers

string

required

Bearer <secret-key>

string

required

The ID of the connection.

string

required

The integration ID for the connection.

Body

string

required

The sync model from which to prune records.

string

required

Records are pruned up to and including this cursor value. Use the _nango_metadata.cursor value from a record.

string

The sync variant to prune records from.

number

Maximum number of records to prune in this request. When omitted, all matching records up to the cursor are pruned.

Response

number

required

Number of records pruned in this request.

boolean

required

true if there are more records to prune up to the given cursor. Send another request with the same until_cursor to continue.

curl -X PATCH "https://api.nango.dev/records/prune" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Connection-Id: user-123" \
  -H "Provider-Config-Key: github" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GithubIssue",
    "until_cursor": "MjAyNC0wMS0xNVQxMDozMTowMC4wMDBafHwxMjM0NTY3"
  }'

const result = await nango.pruneRecords({
  providerConfigKey: 'github',
  connectionId: 'user-123',
  model: 'GithubIssue',
  untilCursor: 'MjAyNC0wMS0xNVQxMDozMTowMC4wMDBafHwxMjM0NTY3'
});

// Paginate until all records are pruned
while (result.has_more) {
  await nango.pruneRecords({ ... });
}

Response

{
  "count": 150,
  "has_more": true
}

Sync execution

Trigger sync

POST /sync/trigger Triggers an immediate, one-off execution of one or more syncs for a connection. Useful after updating connection metadata or when you need to force a fresh import. Use opts.reset to clear the sync checkpoint and re-fetch all data. Use opts.reset with opts.emptyCache to start completely fresh by also clearing the record cache.

Headers

string

required

Bearer <secret-key>

Body

string

required

The integration ID.

array

required

Array of sync names to trigger. Pass an empty array to trigger all syncs for the connection. Each element can be a string (sync name) or an object { name: string; variant: string } to target a specific variant.

string

The connection to trigger the sync for. When omitted, all connections for the integration are triggered.

object

Options for the sync run.

Show properties

boolean

When true, clears the sync checkpoint so all data is re-fetched from the beginning.

boolean

When true (requires reset: true), also clears all cached records before re-syncing.

curl -X POST "https://api.nango.dev/sync/trigger" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_key": "github",
    "syncs": ["github-issues"],
    "connection_id": "user-123"
  }'

// Trigger a specific sync
await nango.triggerSync('github', ['github-issues'], 'user-123');

// Trigger with a full resync (clears checkpoint)
await nango.triggerSync('github', ['github-issues'], 'user-123', {
  reset: true
});

// Trigger all syncs for all connections on an integration
await nango.triggerSync('github', []);

Returns 200 OK with an empty body on success. Node SDK signature

triggerSync(
  providerConfigKey: string,
  syncs?: (string | { name: string; variant: string })[],
  connectionId?: string,
  opts?: { reset?: boolean; emptyCache?: boolean }
): Promise<void>

Start sync

POST /sync/start Resumes a paused sync schedule. Upon starting, the sync executes immediately and then continues on its configured frequency. If the schedule is already running, this has no effect.

Headers

string

required

Bearer <secret-key>

Body

string

required

The integration ID.

array

required

Array of sync names (or { name, variant } objects) to start.

string

The connection to start the sync for. When omitted, the sync is started for all applicable connections.

curl -X POST "https://api.nango.dev/sync/start" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_key": "salesforce",
    "syncs": ["salesforce-contacts"],
    "connection_id": "user-123"
  }'

await nango.startSync('salesforce', ['salesforce-contacts'], 'user-123');

Returns 200 OK with an empty body on success. Node SDK signature

startSync(
  providerConfigKey: string,
  syncs: (string | { name: string; variant: string })[],
  connectionId?: string
): Promise<void>

Pause sync

POST /sync/pause Pauses the schedule for one or more syncs. Paused syncs do not run until restarted with POST /sync/start. In-progress runs complete before the pause takes effect.

Headers

string

required

Bearer <secret-key>

Body

string

required

The integration ID.

array

required

Array of sync names (or { name, variant } objects) to pause.

string

The connection to pause the sync for. When omitted, the sync is paused for all applicable connections.

curl -X POST "https://api.nango.dev/sync/pause" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_key": "github",
    "syncs": ["github-issues"],
    "connection_id": "user-123"
  }'

await nango.pauseSync('github', ['github-issues'], 'user-123');

Returns 200 OK with an empty body on success. Node SDK signature

pauseSync(
  providerConfigKey: string,
  syncs: (string | { name: string; variant: string })[],
  connectionId?: string
): Promise<void>

Get sync status

GET /sync/status Returns the current status of one or more syncs for a connection, including last run time, next scheduled run, checkpoint progress, and record counts.

Headers

string

required

Bearer <secret-key>

Query parameters

string

required

The integration ID.

string

required

Comma-separated list of sync names to get status for, or * to retrieve all syncs for the connection.

string

The connection to get sync status for. When omitted, status for all applicable connections is returned.

Response

object[]

required

Array of sync status objects.

Show sync status properties

string

required

Unique identifier for the sync run.

string

required

The sync name as defined in nango.yaml.

string

required

Current status: RUNNING, SUCCESS, ERROR, PAUSED, or STOPPED.

string

required

The sync’s configured run frequency (for example, every 6 hours).

string

ISO 8601 timestamp of the last completed run, or undefined if it has never run.

string

required

ISO 8601 timestamp of the next scheduled run.

object | null

required

The current sync checkpoint, tracking how far the sync has progressed. null if no checkpoint exists.

object

required

Record of model names to counts of added, updated, and deleted records from the last run.

object

required

Total record counts per model currently stored in Nango’s cache.

curl -X GET "https://api.nango.dev/sync/status?provider_config_key=github&syncs=github-issues&connection_id=user-123" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY"

const { syncs } = await nango.syncStatus('github', ['github-issues'], 'user-123');

// Get all syncs
const { syncs: allSyncs } = await nango.syncStatus('github', '*', 'user-123');

Response

{
  "syncs": [
    {
      "id": "sync_abc123",
      "name": "github-issues",
      "status": "SUCCESS",
      "frequency": "every 6 hours",
      "finishedAt": "2024-03-15T12:00:00.000Z",
      "nextScheduledSyncAt": "2024-03-15T18:00:00.000Z",
      "checkpoint": { "cursor": "2024-03-15T12:00:00.000Z" },
      "latestResult": {
        "GithubIssue": { "added": 3, "updated": 1, "deleted": 0 }
      },
      "recordCount": {
        "GithubIssue": 842
      }
    }
  ]
}

Node SDK signature

syncStatus(
  providerConfigKey: string,
  syncs: '*' | (string | { name: string; variant: string })[],
  connectionId?: string
): Promise<SyncStatusResponse>

Update sync frequency

PUT /sync/update-connection-frequency Overrides the default sync frequency for a specific connection. Pass null for frequency to revert to the default frequency defined in nango.yaml.

Headers

string

required

Bearer <secret-key>

Body

string

required

The integration ID.

string

required

The connection to update the frequency for.

string

required

The sync name as defined in nango.yaml.

string

The sync variant to update frequency for. Omit for the default (base) variant.

string | null

required

New frequency string (for example, every 30 minutes, every 2 hours). Pass null to revert to the default.

Response

string

required

The active frequency for this sync after the update.

curl -X PUT "https://api.nango.dev/sync/update-connection-frequency" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_key": "github",
    "connection_id": "user-123",
    "sync_name": "github-issues",
    "frequency": "every 30 minutes"
  }'

// Override frequency for a specific connection
const result = await nango.updateSyncConnectionFrequency(
  'github',
  'github-issues',
  'user-123',
  'every 30 minutes'
);

// Revert to the default frequency
await nango.updateSyncConnectionFrequency('github', 'github-issues', 'user-123', null);

Response

{
  "frequency": "every 30 minutes"
}

Environment variables

List environment variables

GET /environment-variables Returns all environment variables configured for your Nango environment. These are the variables available to sync and action functions at runtime.

Headers

string

required

Bearer <secret-key>

Response

Array of environment variable objects.

string

required

The variable name.

string

required

The variable value.

curl -X GET "https://api.nango.dev/environment-variables" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY"

const envVars = await nango.getEnvironmentVariables();

Response

[
  { "name": "OPENAI_API_KEY", "value": "sk-..." },
  { "name": "WEBHOOK_SECRET", "value": "whsec_..." }
]

Sync variants

Sync variants allow you to run the same sync with different configurations for a single connection — for example, syncing issues from multiple repositories independently.

The name base is reserved and cannot be used as a variant key. Each variant operates on its own schedule and stores records separately. Query variant records by passing variant to GET /records.

Create sync variant

POST /sync/{name}/variant/{variant} Creates a new variant of an existing sync for a specific connection.

Path parameters

string

required

The sync name as defined in nango.yaml.

string

required

A unique key for this variant. Cannot be base.

Body

string

required

The integration ID.

string

required

The connection to create the variant for.

curl -X POST "https://api.nango.dev/sync/github-issues/variant/repo-frontend" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_key": "github",
    "connection_id": "user-123"
  }'

await nango.createSyncVariant({
  name: 'github-issues',
  variant: 'repo-frontend',
  provider_config_key: 'github',
  connection_id: 'user-123'
});

After creating a variant, fetch its records by including variant in the query:

GET /records?model=GithubIssue&variant=repo-frontend

Delete sync variant

DELETE /sync/{name}/variant/{variant} Deletes a sync variant and all records associated with it.

Path parameters

string

required

The sync name.

string

required

The variant key to delete.

Body

string

required

The integration ID.

string

required

The connection to delete the variant from.

curl -X DELETE "https://api.nango.dev/sync/github-issues/variant/repo-frontend" \
  -H "Authorization: Bearer $NANGO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_key": "github",
    "connection_id": "user-123"
  }'

await nango.deleteSyncVariant({
  name: 'github-issues',
  variant: 'repo-frontend',
  provider_config_key: 'github',
  connection_id: 'user-123'
});

Returns 200 OK with an empty body on success.

​Records

​List records

​Headers

​Query parameters

​Response

​Prune records

​Headers

​Body

​Response

​Sync execution

​Trigger sync

​Headers

​Body

​Start sync

​Headers

​Body

​Pause sync

​Headers

​Body

​Get sync status

​Headers

​Query parameters

​Response

​Update sync frequency

​Headers

​Body

​Response

​Environment variables

​List environment variables

​Headers

​Response

​Sync variants

​Create sync variant

​Path parameters

​Body

​Delete sync variant

​Path parameters

​Body

Records

List records

Headers

Query parameters

Response

Prune records

Headers

Body

Response

Sync execution

Trigger sync

Headers

Body

Start sync

Headers

Body

Pause sync

Headers

Body

Get sync status

Headers

Query parameters

Response

Update sync frequency

Headers

Body

Response

Environment variables

List environment variables

Headers

Response

Sync variants

Create sync variant

Path parameters

Body

Delete sync variant

Path parameters

Body