# List syncs

> List the syncs of the workspace in every region, newest first, with their apps, tables, columns and settings. Deleted syncs are not listed. No `region` parameter: both regions are read.

Source: https://docs.stacksync.com/api-reference/syncs/list_syncs

`GET https://api.stacksync.com/v1/workspaces/{workspace_id}/bases`

- Operation: `list_syncs`
- Resource: Syncs
- Access: read-only

## Authentication

- `Authorization: Bearer <key>`: A workspace API key (workspace_…, created by a workspace owner under Workspace settings > Stacksync API) acts with editor rights on that workspace only; a user API key (user_…, created under Profile > Stacksync API) acts as that user in every workspace they belong to. POST, PUT and PATCH requests must send Content-Type: application/json. Every authentication failure answers 403.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | integer | Yes | The workspace the resources belong to |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string, 3 to 63 characters, pattern `^[A-Za-z0-9_\- ]+$` | No | Only the sync with exactly this name. 3 to 63 characters: unaccented letters (A-Z, a-z), numbers, underscores, dashes and spaces only; unique in the workspace |

## Returns

### 200 The syncs of the workspace

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of object (Sync) | Yes | The syncs, across both regions |
| `data[].base_id` | string (uuid) | Yes | The sync |
| `data[].base_name` | string | Yes | The name of the sync |
| `data[].base_status` | string | Yes | The state of the sync: `running` (switched on), `paused` (switched off), `processing` (a switch is in progress) or an error state set by the platform |
| `data[].base_region` | string (besg \| usnv) | Yes | The data region the sync runs in |
| `data[].settings` | object (SyncSettings) | Yes | The settings of the sync |
| `data[].settings.max_records_sync_delay_in_seconds` | integer | No | The longest a change may wait before it is synced, in seconds; 0 syncs in real time |
| `data[].apps` | array of object (SyncApp), exactly 2 items | Yes | The two apps of the sync |
| `data[].apps[].app_id` | string | Yes | The id of the app inside the sync, used by the app routes (delete protection, rate limit) and by triggers |
| `data[].apps[].app_type` | string | Yes | The app, as shown in Stacksync |
| `data[].apps[].connection_id` | string (uuid) | No | The connection the app uses |
| `data[].apps[].connection_name` | string | No | The name of that connection |
| `data[].apps[].rate_limit` | object (SyncRateLimit) \| null | No | The rate limit of the app, null when Stacksync's default applies |
| `data[].apps[].rate_limit.rate` | integer, 1 to 2147483647 | Yes | The number of requests allowed per period, 1 to 2147483647 |
| `data[].apps[].rate_limit.frequency` | integer (1 \| 60 \| 3600 \| 86400) | Yes | The period of the rate in seconds: 1 (per second), 60 (per minute), 3600 (per hour) or 86400 (per day) |
| `data[].apps[].delete_protection` | boolean | Yes | Whether deletes are kept from reaching this app |
| `data[].apps[].bulk_api_access` | boolean | Yes | Whether the Salesforce Bulk API is used for this app |
| `data[].apps[].cdc_method` | string \| null | No | How changes are captured from this app (for example `triggers`, `logical_replication`, `webhook`); null when not applicable |
| `data[].apps[].tables` | array of object (SyncTable) | Yes | The synced tables of the app |
| `data[].apps[].tables[].table_name` | string | Yes | The name of the table in the app |
| `data[].apps[].tables[].table_mapping_id` | string | Yes | The id shared by the two tables of a pair |
| `data[].apps[].tables[].sync_direction` | string (bidirectional \| incoming \| outgoing) | No | `bidirectional` (read and written), `incoming` (only written into) or `outgoing` (only read from) |
| `data[].apps[].tables[].columns` | array of object (SyncColumn) | Yes | The synced columns of the table |
| `data[].apps[].tables[].columns[].column_name` | string | Yes | The name of the column in the app |
| `data[].apps[].tables[].columns[].column_mapping_id` | string | Yes | The id shared by the two columns of a pair |
| `data[].apps[].tables[].columns[].column_sync_direction` | string (bidirectional \| incoming \| outgoing \| null) | No | The direction of this column when it differs from the table's: `bidirectional`, `incoming` or `outgoing`; null for the table's |

## Example request

```bash
curl -X GET "https://api.stacksync.com/v1/workspaces/{workspace_id}/bases" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY"
```

## Example response (200)

```json
{
  "data": [
    {
      "base_id": "3f6c1d2e-8a4b-4c7d-9e21-5b6f7a8c9d01",
      "base_name": "Salesforce accounts to Postgres",
      "base_status": "running",
      "base_region": "usnv",
      "settings": {
        "max_records_sync_delay_in_seconds": 0
      },
      "apps": [
        {
          "app_id": "3f9a1c2e",
          "app_type": "salesforce",
          "connection_id": "c7d8e9f0-2a3b-4c5d-9e6f-7a8b9c0d1e2f",
          "connection_name": "Salesforce production",
          "rate_limit": {
            "rate": 50,
            "frequency": 1
          },
          "delete_protection": false,
          "bulk_api_access": false,
          "cdc_method": null,
          "tables": [
            {
              "table_name": "Account",
              "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
              "sync_direction": "bidirectional",
              "columns": [
                {
                  "column_name": "Name",
                  "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
                },
                {
                  "column_name": "Website",
                  "column_mapping_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
                }
              ]
            }
          ]
        },
        {
          "app_id": "b71d04e5",
          "app_type": "postgres",
          "connection_id": "9b2e4f60-1c3d-4a5e-8f70-2d4c6e8a0b12",
          "connection_name": "Production Postgres",
          "rate_limit": null,
          "delete_protection": true,
          "bulk_api_access": false,
          "cdc_method": "triggers",
          "tables": [
            {
              "table_name": "accounts",
              "table_mapping_id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
              "sync_direction": "bidirectional",
              "columns": [
                {
                  "column_name": "name",
                  "column_mapping_id": "1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
                },
                {
                  "column_name": "website",
                  "column_mapping_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

## Errors

| Status | Meaning | Body |
| --- | --- | --- |
| 400 | `name` is not a string of 3 to 63 allowed characters (`Invalid Request Body`); the syncs could not be read (`Error retrieving bases`) | `{ "error": string }` |
| 403 | Forbidden: invalid API key, API key of another workspace, insufficient scope, workspace unavailable, or a non-GET request without `Content-Type: application/json` | `{ "error": string }` |

## Related

- [API Reference overview](https://docs.stacksync.com/api-reference): base URLs, regions, pagination, idempotency and errors
- [Authentication](https://docs.stacksync.com/api-reference/authentication): API keys and the 403 answers
- OpenAPI document: https://docs.stacksync.com/openapi.json
- [Get a sync](https://docs.stacksync.com/api-reference/syncs/get_sync)
- [Get the status of a sync](https://docs.stacksync.com/api-reference/syncs/get_sync_status)
- [Get sync metrics](https://docs.stacksync.com/api-reference/syncs/get_sync_metrics)
- [Get sync diagnostics](https://docs.stacksync.com/api-reference/syncs/get_sync_diagnostics)
- [Create a sync](https://docs.stacksync.com/api-reference/syncs/create_sync)
- [Update sync settings](https://docs.stacksync.com/api-reference/syncs/update_sync_settings)
- [Edit a sync](https://docs.stacksync.com/api-reference/syncs/edit_sync)
- [Delete a sync](https://docs.stacksync.com/api-reference/syncs/delete_sync)
- [Rename a sync](https://docs.stacksync.com/api-reference/syncs/rename_sync)
- [Switch a sync on or off](https://docs.stacksync.com/api-reference/syncs/switch_sync)
- [Set the change capture method](https://docs.stacksync.com/api-reference/syncs/set_sync_app_cdc_method)
- [Set the rate limit of an app](https://docs.stacksync.com/api-reference/syncs/set_sync_app_rate_limit)
- [Set Salesforce Bulk API access](https://docs.stacksync.com/api-reference/syncs/set_sync_app_bulk_api_access)
- [Set delete protection of an app](https://docs.stacksync.com/api-reference/syncs/set_sync_app_delete_protection)