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

Authorization

string

required

Bearer <secret-key>

Connection-Id

string

required

The ID of the connection to fetch records for.

Provider-Config-Key

string

required

The integration ID (unique key) for the connection.

Query parameters

model

string

required

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

variant

string

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

modified_after

string

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

filter

string

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

cursor

string

Pagination cursor from the previous response’s next_cursor field.

limit

number

default:"100"

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

ids

string[]

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

Response

records

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.

_nango_metadata

object

required

Nango-managed metadata for this record.

Show properties

last_action

string

required

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

first_seen_at

string

required

ISO 8601 timestamp when this record was first synced.

last_modified_at

string

required

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

deleted_at

string | null

required

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

cursor

string

required

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

next_cursor

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"

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

Authorization

string

required

Bearer <secret-key>

Connection-Id

string

required

The ID of the connection.

Provider-Config-Key

string

required

The integration ID for the connection.

Body

model

string

required

The sync model from which to prune records.

until_cursor

string

required

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

variant

string

The sync variant to prune records from.

limit

number

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

Response

count

number

required

Number of records pruned in this request.

has_more

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"
  }'

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

Authorization

string

required

Bearer <secret-key>

Body

provider_config_key

string

required

The integration ID.

syncs

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.

connection_id

string

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

opts

object

Options for the sync run.

Show properties

opts.reset

boolean

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

opts.emptyCache

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"
  }'

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

Authorization

string

required

Bearer <secret-key>

Body

provider_config_key

string

required

The integration ID.

syncs

array

required

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

connection_id

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"
  }'

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

Authorization

string

required

Bearer <secret-key>

Body

provider_config_key

string

required

The integration ID.

syncs

array

required

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

connection_id

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"
  }'

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

Authorization

string

required

Bearer <secret-key>

Query parameters

provider_config_key

string

required

The integration ID.

syncs

string

required

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

connection_id

string

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

Response

syncs

object[]

required

Array of sync status objects.

Show sync status properties

string

required

Unique identifier for the sync run.

name

string

required

The sync name as defined in nango.yaml.

status

string

required

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

frequency

string

required

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

finishedAt

string

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

nextScheduledSyncAt

string

required

ISO 8601 timestamp of the next scheduled run.

checkpoint

object | null

required

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

latestResult

object

required

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

recordCount

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"

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

Authorization

string

required

Bearer <secret-key>

Body

provider_config_key

string

required

The integration ID.

connection_id

string

required

The connection to update the frequency for.

sync_name

string

required

The sync name as defined in nango.yaml.

sync_variant

string

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

frequency

string | null

required

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

Response

frequency

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"
  }'

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

Authorization

string

required

Bearer <secret-key>

Response

Array of environment variable objects.

name

string

required

The variable name.

value

string

required

The variable value.

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

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

name

string

required

The sync name as defined in nango.yaml.

variant

string

required

A unique key for this variant. Cannot be base.

Body

provider_config_key

string

required

The integration ID.

connection_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"
  }'

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

name

string

required

The sync name.

variant

string

required

The variant key to delete.

Body

provider_config_key

string

required

The integration ID.

connection_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"
  }'

Returns 200 OK with an empty body on success.

Overview

Integrations & Connections

Functions & Proxy

SDKs

​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

Build docs developers (and LLMs) love

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