The Nango SDK is rate-limited to prevent abuse and ensure fair usage across all clients. The rate limit is enforced on a per-account basis, with a fixed window of time and a maximum number of requests allowed within that window.
If a client exceeds the rate limit, the API will respond with a 429 Too Many Requests status code. In this case, the Retry-After header is included, indicating the number of seconds the client should wait before making another request to avoid being rate-limited.
To handle rate limiting gracefully, clients should monitor for the 429 status code and honor the Retry-After header value provided in the response.
// Example:try{const res =await nango.listIntegrations();...}catch(err){if(err.response.status===429){const retryAfter = err.response.headers['retry-after'];// wait and retry...}...}
The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth, etc.).
If you do not want to deal with collecting & injecting credentials in requests for multiple authentication types, use the Proxy (step-by-step guide).
When you fetch the connection with this API endpoint, Nango will check if the access token has expired. If it has, it will refresh it.
We recommend not caching tokens for longer than 5 minutes to ensure they are fresh.
Parameters
providerConfigKey
string
required
The integration ID.
connectionId
string
required
The connection ID.
forceRefresh
boolean
Defaults to false. If false, the token will only be refreshed if it expires within 15 minutes. If true, a token refresh attempt will happen on each request. This is only useful for testing and should not be done at high traffic.
refreshToken
boolean
Defaults to false. If false, the refresh token is not included in the response, otherwise it is. In production, it is not advised to return the refresh token, for security reasons, since only the access token is needed to sign requests.
Example Response
{"id":18393,"created_at":"2023-03-08T09:43:03.725Z","updated_at":"2023-03-08T09:43:03.725Z","provider_config_key":"github","connection_id":"1","credentials":{"type":"OAUTH2","access_token":"gho_tsXLG73f....","refresh_token":"gho_fjofu84u9....","expires_at":"2024-03-08T09:43:03.725Z","raw":{// Raw token response from the OAuth provider: Contents vary!"access_token":"gho_tsXLG73f....","refresh_token":"gho_fjofu84u9....","token_type":"bearer","scope":"public_repo,user"}},"connection_config":{"subdomain":"myshop","realmId":"XXXXX","instance_id":"YYYYYYY"},"account_id":0,"metadata":{"myProperty":"yes","filter":"closed=true"}}
Set custom metadata for the connection or connections (overrides existing metadata).
await nango.setMetadata('<INTEGRATION-ID>','CONNECTION-ID',{'CUSTOM_KEY1':'CUSTOM_VALUE1'});# set an array of connection idsawait nango.setMetadata('<INTEGRATION-ID>',['CONNECTION-ID','CONNECTION-ID-TWO'],{'CUSTOM_KEY1':'CUSTOM_VALUE1'});
Edit custom metadata for the connection or connections. Only overrides specified properties, not the entire metadata.
await nango.updateMetadata('<INTEGRATION-ID>','CONNECTION-ID',{'CUSTOM_KEY1':'CUSTOM_VALUE1'});# update an array of connection idsawait nango.updateMetadata('<INTEGRATION-ID>',['CONNECTION-ID','CONNECTION-ID-TWO'],{'CUSTOM_KEY1':'CUSTOM_VALUE1'});
[{"providerConfigKey":"demo-github-integration","syncs":[{"name":"github-issue-example","type":"sync","models":[{"name":"GithubIssue","fields":[{"name":"id","type":"integer"},{"name":"owner","type":"string"},{"name":"repo","type":"string"},{"name":"issue_number","type":"number"},{"name":"title","type":"string"},{"name":"author","type":"string"},{"name":"author_id","type":"string"},{"name":"state","type":"string"},{"name":"date_created","type":"date"},{"name":"date_last_modified","type":"date"},{"name":"body","type":"string"}]}],"sync_type":"FULL","runs":"every half hour","track_deletes":false,"auto_start":false,"last_deployed":"2024-02-28T20:16:38.052Z","is_public":false,"pre_built":false,"version":"4","attributes":{},"input":{},"returns":["GithubIssue"],"description":"Fetches the Github issues from all a user's repositories.\nDetails: full sync, doesn't track deletes, metadata is not required.\n","scopes":["public_repo"],"endpoints":[{"GET":"/github/issue-example"}],"nango_yaml_version":"v2","webhookSubscriptions":[]}],"actions":[{"name":"fetch-issues","type":"action","models":[{"name":"GithubIssue","fields":[{"name":"id","type":"integer"},{"name":"owner","type":"string"},{"name":"repo","type":"string"},{"name":"issue_number","type":"number"},{"name":"title","type":"string"},{"name":"author","type":"string"},{"name":"author_id","type":"string"},{"name":"state","type":"string"},{"name":"date_created","type":"date"},{"name":"date_last_modified","type":"date"},{"name":"body","type":"string"}]}],"runs":"","is_public":false,"pre_built":false,"version":"4","last_deployed":"2024-02-28T20:16:38.052Z","attributes":{},"returns":["GithubIssue"],"description":"","scopes":[],"input":{},"endpoints":[{"GET":"/github/issues"}],"nango_yaml_version":"v2"}],"postConnectionScripts":[],"provider":"github"}]
importtype{ ModelName }from'<path-to-nango-integrations>/models'const records =await nango.listRecords<ModelName>({ providerConfigKey:'<INTEGRATION-ID>', connectionId:'<CONNECTION-ID>', model:'<MODEL-NAME>'});
nango.getRecords() is deprecated and will be removed in future releases as it does not support efficient pagination. Please use nango.listRecords() detailed below.
Parameters
config
object
required
providerConfigKey
string
required
The integration ID.
connectionId
string
required
The connection ID.
model
string
required
The name of the model of the data you want to retrieve.
cursor
string
Each record from this endpoint comes with a synchronization cursor in _nango_metadata.cursor.
Save the last fetched record’s cursor to track how far you’ve synced.
By providing the cursor to this method, you’ll continue syncing from where you left off, receiving only post-cursor changes.
This same cursor is used to paginate through the results of this endpoint.
limit
number
The maximum number of records to return. Defaults to 100.
filter
string
Filter to only show results that have been added or updated or deleted.
Available options: added, updated, deleted
modifiedAfter
string
Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed, only records modified after this timestamp are returned, otherwise all records are returned.
delta
string
DEPRECATED (use modifiedAfter) Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed, only records modified after this timestamp are returned, otherwise all records are returned.
Example Response
This endpoint returns a list of records, ordered by modification date ascending. If some records are updated while you paginate through this endpoint, you might see these records multiple times.
{ records:[{ id:123, ...,// Fields as specified in the model you queried _nango_metadata:{ deleted_at:null, last_action: 'ADDED', first_seen_at: '2023-09-18T15:20:35.941305+00:00', last_modified_at: '2023-09-18T15:20:35.941305+00:00', cursor: 'MjAyNC0wMi0yNlQwMzowMDozOS42MjMzODgtMDU6MDB8fGVlMDYwM2E1LTEwNDktNDA4Zi05YTEwLTJjNzVmNDkwODNjYQ=='}}, ...], next_cursor:"Y3JlYXRlZF9hdF4yMDIzLTExLTE3VDExOjQ3OjE0LjQ0NyswMjowMHxpZF4xYTE2MTYwMS0yMzk5LTQ4MzYtYWFiMi1mNjk1ZWI2YTZhYzI"}
Starts the schedule of specified sync(s) for a given connection or all applicable connections if no connection is specified. Upon starting the schedule, the sync will execute immediately and then continue to run at the specified frequency. If the schedule was already started, this will have no effect.
The frequency you want to set (ex: ‘every hour’). Set to null to revert to the default frequency. Uses the https://github.com/vercel/ms notations. Min frequency: 5 minutes.
const{ data }=await nango.createConnectSession({end_user:{id:'<END-USER-ID>',email:'<END-USER-EMAIL>',display_name:'<END-USER-NAME>'},organization:{id:'<ORGANIZATION-ID>',display_name:'<ORGANIZATION-NAME>'},allowed_integrations:['<INTEGRATION-ID-1>','<INTEGRATION-ID-2>'],integrations_config_defaults:{<INTEGRATION-ID-1>:{connection_config:{<CONFIG-KEY>:'<VALUE>'}}}});
Parameters
end_user
object
required
id
string
required
The unique identifier for the end user.
email
string
required
The email address of the end user.
display_name
string
The display name of the end user.
organization
object
id
string
required
The unique identifier for the organization.
display_name
string
The display name of the organization.
allowed_integrations
string[]
An array of integration IDs that are allowed for this session.
Create a reconnect session for a given connection_id. Optionally, you can set end_user and organization to update those attributes of the connection.
Use this method when a user needs to input new credentials or to manually refresh token.
const{ data }=await nango.createConnectSession({connection_id:'<CONNECTION-ID>'integration_id:'<INTEGRATION-ID>',end_user:{id:'<END-USER-ID>',email:'<END-USER-EMAIL>',display_name:'<END-USER-NAME>'},organization:{id:'<ORGANIZATION-ID>',display_name:'<ORGANIZATION-NAME>'},integrations_config_defaults:{<INTEGRATION-ID-1>:{connection_config:{<CONFIG-KEY>:'<VALUE>'}}}});