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 service access token in the RudderStack dashboard with the relevant permissions.

For production use cases, RudderStack recommends using a service access token instead of personal access token.

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:

Your service access token must have the relevant permissions to authenticate the API and 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 service access token must have the relevant permissions to authenticate the API and 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 service access token must have the relevant permissions to authenticate the API and 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 cancel a sync for a Reverse ETL connection using the below endpoint:

Your service access token must have the relevant permissions to authenticate the API and 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:

Which permissions should I assign to the service access token for using the Reverse ETL Connections API?

For a workspace-level service access token, you should set the following permissions for the token to use the relevant Connection API endpoints:

Questions? Contact us by email or on Slack