---
title: "List syncs"
method: GET
path: "/v1/sync/syncs"
tags: ["Syncs"]
---

# List syncs

`GET /v1/sync/syncs`

## Request

- Base URL: `https://api.whalesync.com`
- URL: `https://api.whalesync.com/v1/sync/syncs`
- Auth: HTTP bearer

Every sync on the API key's account, newest first.

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

A page of syncs, newest first.

- SyncList
  - `data` Sync[], required
    - `id` string, required
    - `name` string, required
    - `status` 'draft' | 'active' | 'paused', required
    - `left` SyncSide, required
      - `side` 'left' | 'right', required
      - `connector` string, required
      - `base` SyncSideBase, required
        - `remote_id` string, required: The base id in the connector, stable across renames.
        - `name` string, required: The base name as shown by the connector.
        - `url` string, uri, nullable, required: A link to open the base in its own service, if any.
      - `auth_status` 'connected' | 'error', required: `error` means the side needs reconnecting.
      - `auth_error` string, nullable, required: A generic code for the auth failure when `auth_status` is `error`.
      - `other_active_syncs` number, required: How many other active syncs in the account use this same base. Two syncs writing to one base can overwrite each other and create duplicates.
      - `tables_url` string, uri, required: This side's tables.
    - `right` SyncSide, required
      - `side` 'left' | 'right', required
      - `connector` string, required
      - `base` SyncSideBase, required
        - `remote_id` string, required: The base id in the connector, stable across renames.
        - `name` string, required: The base name as shown by the connector.
        - `url` string, uri, nullable, required: A link to open the base in its own service, if any.
      - `auth_status` 'connected' | 'error', required: `error` means the side needs reconnecting.
      - `auth_error` string, nullable, required: A generic code for the auth failure when `auth_status` is `error`.
      - `other_active_syncs` number, required: How many other active syncs in the account use this same base. Two syncs writing to one base can overwrite each other and create duplicates.
      - `tables_url` string, uri, required: This side's tables.
    - `mappings_revision` string, required: Opaque revision of the mappings document; changes on every mappings edit. Doubles as the mappings ETag — compare it across polls to detect edits made in the app during a handoff.
    - `open_issues` number, required: Unresolved issues across both sides. Read the detail from `GET /v1/sync/issues?sync=…`.
    - `delete_approval` 'review_required' | 'auto_approve', required: `review_required` means a record that goes missing on one side waits for a person to approve the delete before it is applied to the other side; `auto_approve` means deletes are applied as soon as they are detected, and there is no queue to read.
    - `pending_deletes` number, required: Deletes waiting on a person right now. Always 0 under `auto_approve`, where nothing waits. Read the detail from `GET /v1/sync/pending-deletes?sync=…`.
    - `initial_sync_running` boolean, required: Whether the initial sync is running: the first match and copy of records between the two apps, started when a person activates the sync. `status` is `paused` until it finishes and the sync turns on.
    - `initial_sync_preparing` boolean, required: Whether the initial sync is being prepared: Whalesync is downloading records and planning the match. When that finishes it waits for a person to review and start it. Activating the sync meanwhile fails with `initial_sync_preparing`.
    - `last_synced_at` string, date-time, nullable, required: When the sync last polled, or null if never.
    - `created_at` string, date-time, required
    - `review_url` string, uri, required: The sync's page in the app, where a human reviews the mappings and starts it.
    - `app_url` string, uri, required: The sync in the Whalesync app, for a person browsing — unlike review_url, nothing here needs their attention (a first-time draft is started from review_url).
    - `pending_actions` PendingAction[], required: What a person still has to do in the browser before this sync can run: connect a side whose app signs in there, then review and start it. Empty when nothing is waiting on anyone. Agents cannot perform these — relay the `instruction` and `url`.
      - `type` 'user_authorization' | 'user_confirmation' | 'user_api_key', required
      - `audience` 'end_user', required: Who has to do this. `end_user` means a person — not the agent, and not the API.
      - `action` 'open_in_browser', required: What to do with `url`: open it in a browser. It is a page for a person, never an endpoint to call.
      - `side` 'left' | 'right' | 'source' | 'destination' | 'null', nullable, required: The side this is about, when it is one side. Syncs have `left`/`right`; live exports have `source`/`destination`.
      - `connector` string, nullable, required: The app to connect, when we know which one was asked for.
      - `url` string, uri, required: The page to hand to the person.
      - `instruction` string, required: Plain-language instruction, safe to relay to the person verbatim.
    - `url` string, uri, required: Canonical URL of this sync in the API.
    - `status_url` string, uri, required: This sync's live status snapshot.
    - `mappings_url` string, uri, required: This sync's mappings document.
    - `operations_url` string, uri, required: This sync's operations, pre-filtered.
    - `issues_url` string, uri, required: This sync's issues, pre-filtered.
    - `pending_deletes_url` string, uri, required: This sync's delete queue, pre-filtered.
  - `has_more` boolean, required: Whether more syncs follow this page.
  - `next_cursor` string, nullable, required: Pass back as `cursor` to fetch the next page.

## Other responses

- `401`: The API key is missing, invalid, or revoked (`missing_api_key`, `invalid_api_key`). Carries a `required_action` linking a person to key creation, naming the smallest scope this endpoint needs.
- `403`: The key's scope does not allow this call (`insufficient_scope` on a mutation with a `read` key).
- `429`: Rate limit exceeded. Wait for `Retry-After` seconds.

---

[API](https://skmtc.dev/whalesync/apis/whalesync-api.md) · [All operations](https://skmtc.dev/whalesync/apis/whalesync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whalesync/apis/whalesync-api/revisions/5131522b325a?raw)