Reverse ETL Connections API

The Reverse ETL Connections API lets you programmatically run syncs for your Reverse ETL connections.

You can use this API to:

• Trigger a new sync for a particular connection.
• Get details of all syncs for a connection.
• Stop a running sync for a connection.

Prerequisites

• Get the connection ID for which you want to start/stop syncs from the RudderStack dashboard.
• Generate a personal access token in the RudderStack dashboard. Note that your personal access token should have the following permissions to use the associated API endpoints:

Authentication

The Reverse ETL Connections API uses Bearer authentication in the following format:

Authorization: Bearer <PERSONAL_ACCESS_TOKEN>

Base URL

Use the base URL for your API requests depending on your region:

https://api.rudderstack.com/v2

https://api.eu.rudderstack.com/v2

Start sync

You can start a new sync for a Reverse ETL connection using the below endpoint:

Your personal access token must have Read-Write or Admin permissions for authenticating the API to run this endpoint.

Path parameters

Request body

Example request

POST /v2/retl-connections/<connection_id>/start HTTP/1.1
Host: api.rudderstack.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  "syncType": "incremental"  // Other acceptable values: full
}

curl --location 'https://api.rudderstack.com/v2/retl-connections/<connection_id>/start' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "syncType": "incremental"  // Other acceptable values: full
}'

Example response

{
   “syncId”: “<sync_id>"
}

Response codes

Get sync details

Use the following endpoints to get details of all syncs or an individual sync for a particular Reverse ETL connection. You can also filter the results by sync status, start time, and limit the number of results per page.

All syncs

Your personal access token must have Read-Only, Read-Write or Admin permissions for authenticating the API to run this endpoint.

Path parameters

Query parameters

Example request

GET /v2/retl-connections/<connection_id>/syncs?status=<status>>&started_after=<started_after_date>&started_before=<started_before_date>&per_page=<results_per_page>>&page=<page_number> HTTP/1.1
Host: api.rudderstack.com
Accept: application/json
Authorization: Bearer <token>

curl --location 'https://api.rudderstack.com/v2/retl-connections/<connection_id>/syncs?status=<status>&started_after=<started_after_time>&started_before=<started_before_time>&per_page=<results_per_page>>&page=<page_number>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'

Example response

{
  "syncs": [{
    "id": "<sync_id>",
    "status": "running",
    "startedAt": "2024-04-20T05:41:18.871Z",
    "finishedAt": "2024-04-20T05:41:18.871Z",
    "error": "<string>",
    "metrics": {
      "succeeded": {
        "total": 0
      },
      "failed": {
        "total": 0
      },
      "changed": {
        "total": 0
      },
      "total": 0
    }
  }],
  "paging": {
    "total": 200,
    "next": "/<collection path>?page=2"
  }
}

Response codes

Individual sync

Your personal access token must have Read-Only, Read-Write or Admin permissions for authenticating the API to run this endpoint.

Path parameters

You can find the sync ID from the /start endpoint response.

Example request

GET /v2/retl-connections/<connection_id>/syncs/<sync_id> HTTP/1.1
Host: api.rudderstack.com
Accept: application/json
Authorization: Bearer <token>

curl --location 'https://api.rudderstack.com/v2/retl-connections/<connection_id>/syncs/<sync_id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'

Example response

{
  "id": "<sync_id>",
  "status": "running",
  "startedAt": "2024-04-20T05:58:14.778Z",
  "finishedAt": "2024-04-20T05:58:14.778Z",
  "error": "<string>",
  "metrics": {
    "succeeded": {
      "total": 0
    },
    "failed": {
      "total": 0
    },
    "changed": {
      "total": 0
    },
    "total": 0
  }
}

Response codes

Cancel sync

You can start a new sync for a Reverse ETL connection using the below endpoint:

Your personal access token must have Read-Write or Admin permissions for authenticating the API to run this endpoint.

Path parameters

Example request

POST /v2/retl-connections/<connection_id>/stop HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer <token>

curl --location --request POST 'https://api.rudderstack.com/v2/retl-connections/<connection_id>/stop' \
--header 'Authorization: Bearer <token>'

Example response

FAQ

Where can I find the connection ID for a Reverse ETL connection?

Go to the Settings tab of the connection to get the Connection ID for a particular Reverse ETL connection:

How to generate a personal access token to use the Reverse ETL Connections API?

To generate your personal access token, go to Settings > Your Profile > Account tab. Scroll down to Personal access tokens and click Generate new token.

Enter the token name and choose Admin role from the dropdown:

Your personal access token should have the following permissions to use the associated endpoints:

Questions? Contact us by email or on Slack