RudderStack 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 workspace-level Service Access Token in the RudderStack dashboard with the following permissions to use the various API endpoints:

Token permissions for legacy RBAC system

If you are on the legacy Permissions Management (RBAC) system, your workspace-level Service Access Token should have minimum Admin permissions.

See this documentation for more information on generating the token.

The token leverages the following permissions for various endpoints:

Authentication

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

Authorization: Bearer <SERVICE_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:

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

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

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 cancel a sync for a Reverse ETL connection using the below 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

See also

• Trigger Syncs from dbt Cloud using the Reverse ETL Connections API

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: