# 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](#faq) for which you want to start/stop syncs from the RudderStack dashboard.
- Generate a [workspace-level Service Access Token]({{< ref "access-management/service-access-tokens.md#workspace-sat" >}}) in the RudderStack dashboard with the following [permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to use the various API endpoints:

| Resource | Permission |
| :----| :-----|
| Tables / SQL Models / Audiences | **Edit**, **Connect** |
| Destinations | **Edit**, **Connect** | 
| PII permissions  <br/> <span style="color: #4D4DFF;font-size:12px;">Enterprise plan only</span> | **Reverse ETL Sync Failure Samples** configured for the required source | 

#### Token permissions for legacy RBAC system

If you are on the [legacy Permissions Management (RBAC) system]({{< ref "archive/dashboard-guides/user-management.md" >}}), your workspace-level Service Access Token should have minimum **Admin** permissions.

See [this documentation]({{< ref "archive/dashboard-guides/service-access-tokens.md#generate-service-access-token" >}}) for more information on generating the token.

{{< image src="images/access-management/permissions/legacy/admin.webp" alt="workspace-level Service Access Token with Admin permission" >}}

The token leverages the following permissions for various endpoints:

| Endpoint |  Permissions |
| :----| :----| 
| [`/start`](#start-sync) | Editor, Admin  |
| [`/syncs`](#all-syncs) | Viewer, Editor, Admin | 
| [`/syncs/{syncId}`](#individual-sync) | Viewer, Editor, Admin | 
| [`/stop`](#cancel-sync) | Editor, Admin  |

## Authentication

The Reverse ETL Connections API uses [Bearer authentication](https://swagger.io/docs/specification/authentication/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:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Standard" %}}
```text
https://api.rudderstack.com/v2
```
{{% /tab %}}
{{% tab tabName="EU-Standard" %}}
```text
https://api.eu.rudderstack.com/v2
```
{{% /tab %}}
{{< /tabs >}}

## Start sync

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

{{% api-method method="post" host="https://api.rudderstack.com/v2" path="/retl-connections/{connectionId}/start" %}}

**Path parameters**

{{< query-params keyname="connectionId" valuename="Connection ID for which RudderStack starts a new sync" keytype="Required" datatype="String" >}}
<hr/>

**Request body**

{{< query-paramsList >}}
  {{< query-params keyname="syncType" valuename="Specify the scope of sync. It can be one of the following: <br /><br /><ul><li>`incremental`: RudderStack syncs only the newly added data in the warehouse since the last sync.</li><li>`full`: RudderStack syncs all the data irrespective of whether it was synced to the destination previously.</li></li></ul>" keytype="Required" datatype="String" >}}
{{< /query-paramsList >}}

**Example request**

{{< tabs tabTotal="2" >}}
{{% tab tabName="HTTP" %}}
```http
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
}
```
{{% /tab %}}
{{% tab tabName="CURL" %}}
```bash
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
}'
```
{{% /tab %}}
{{< /tabs >}}

**Example response**

```json
{
   “syncId”: “<sync_id>"
}
```

**Response codes**

| Code | Description |
| :----| :---|
| 200 | Sync started for Reverse ETL connection. <br /><br />RudderStack also returns a unique ID for the newly created sync. | 
| 404 | Reverse ETL connection was not found for the specified connection ID. |
| 409 | A Reverse ETL sync is already running for the specified connection ID. |

## Get sync details

Use the following endpoints to get details of [all syncs](#all-syncs) or an [individual sync](#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

{{% api-method method="get" host="https://api.rudderstack.com/v2" path="/retl-connections/{connectionId}/syncs" %}}

**Path parameters**

{{< query-params keyname="connectionId" valuename="Connection ID for which RudderStack fetches the syncs details." keytype="Required" datatype="String" >}}

**Query parameters**

{{< query-params keyname="status" valuename="Filter syncs by status. It accepts one of the following values - `running`, `succeeded`, and `failed`." keytype="Optional" datatype="String" >}}
{{< query-params keyname="started_after" valuename="Filter syncs started after the specified time (in UTC)." keytype="Optional" datatype="String (datetime)" >}}
{{< query-params keyname="started_before" valuename="Filter syncs started before the specified time (in UTC)." keytype="Optional" datatype="String (datetime)" >}}
{{< query-params keyname="per_page" valuename="Limit the number of results shown in the page." keytype="Optional" datatype="Integer" >}}
{{< query-params keyname="page" valuename="Show a particular page in the results." keytype="Optional" datatype="Integer" >}}
<hr/>

**Example request**

{{< tabs tabTotal="2" >}}
{{% tab tabName="HTTP" %}}
```http
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>
```
{{% /tab %}}
{{% tab tabName="CURL" %}}
```bash
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>'
```
{{% /tab %}}
{{< /tabs >}}

**Example response**

```json
{
  "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**

| Code | Description |
| :----|  :---|
| 200 | List of all Reverse ETL syncs for the specified connection ID. | 
| 404 | Reverse ETL connection was not found for the specified connection ID. |

### Individual sync

{{% api-method method="get" host="https://api.rudderstack.com/v2" path="/retl-connections/{connectionId}/syncs/{syncId}" %}}

**Path parameters**

{{< query-params keyname="connectionId" valuename="Connection ID for which RudderStack fetches the syncs details." keytype="Required" datatype="String" >}}
{{< query-params keyname="syncId" valuename="ID for a particular Reverse ETL sync." keytype="Required" datatype="String" >}}

{{< info >}}
You can find the sync ID from the [`/start`](#start-sync) endpoint response.
{{< /info >}}

**Example request**

{{< tabs tabTotal="2" >}}
{{% tab tabName="HTTP" %}}
```http
GET /v2/retl-connections/<connection_id>/syncs/<sync_id> HTTP/1.1
Host: api.rudderstack.com
Accept: application/json
Authorization: Bearer <token>
```
{{% /tab %}}
{{% tab tabName="CURL" %}}
```bash
curl --location 'https://api.rudderstack.com/v2/retl-connections/<connection_id>/syncs/<sync_id>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'
```
{{% /tab %}}
{{< /tabs >}}

**Example response**

```json
{
  "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**

| Code | Description |
| :----|  :---|
| 200 | Sync details for the specified connection ID and sync ID. |
| 404 | Reverse ETL connection was not found for the specified connection ID. |

## Cancel sync

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

{{% api-method method="post" host="https://api.rudderstack.com/v2" path="/retl-connections/{connectionId}/stop" %}}

**Path parameters**

{{< query-params keyname="connectionId" valuename="Connection ID for which RudderStack starts a new sync" keytype="Required" datatype="String" >}}
<hr/>

**Example request**

{{< tabs tabTotal="2" >}}
{{% tab tabName="HTTP" %}}
```http
POST /v2/retl-connections/<connection_id>/stop HTTP/1.1
Host: api.rudderstack.com
Authorization: Bearer <token>
```
{{% /tab %}}
{{% tab tabName="CURL" %}}
```bash
curl --location --request POST 'https://api.rudderstack.com/v2/retl-connections/<connection_id>/stop' \
--header 'Authorization: Bearer <token>'
```
{{% /tab %}}
{{< /tabs >}}

**Example response**

| Code | Response | Description |
| :----| :-----| :---|
| 204 | Stop was requested. | RudderStack has successfully sent a cancellation request to stop the Reverse ETL connection sync. | 
| 404 | - | Reverse ETL connection was not found for the specified connection ID. |

## See also

- [Trigger Syncs from dbt Cloud]({{< ref "data-pipelines/reverse-etl/developer-guides/trigger-syncs-from-dbt-cloud.md" >}}) 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:

{{< image src="images/retl-sources/connection-id.webp" alt="connection ID for Reverse ETL" >}}

<br />