---
title: "Search records"
method: GET
path: "/v1/sync/records"
tags: ["Records"]
---

# Search records

`GET /v1/sync/records`

## Request

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

Finds records in one sync by the record's id in the connected app (e.g. an Airtable "rec…" id), a Whalesync `rec_` id, or display text. Exact id matches come first. Results are capped, not paginated — when `has_more` is true, narrow the query. Each hit links to its status document.

## Query parameters

- `sync` string, required
- `query` string, required
- `table` string
- `limit` integer

## Response `200`

The matching records, best matches first.

- RecordList
  - `data` RecordSummary[], required
    - `id` string, required
    - `sync_id` string, required
    - `side` 'left' | 'right', required: The side of the sync this match was found on.
    - `remote_id` string, nullable, required: The record id in the connected app.
    - `name` string, nullable, required: A display name for the record, if one is known.
    - `table` RecordTable, required
      - `id` string, required
      - `remote_id` string, required: The table id in the connector, stable across renames.
      - `name` string, required
    - `is_deleted` boolean, required: Whether this copy of the record has been deleted.
    - `is_sync_disabled` boolean, required: Whether syncing is turned off for this record via a sync-enabled field.
    - `url` string, uri, required: The record's status document — the next call to make.
    - `browser_url` string, uri, nullable, required: Opens this copy of the record in the connected app, when the app has record links. Named apart from `url`, which is this record in the API.
    - `app_url` string, uri, required: The record's status page in the Whalesync app, for a person looking closer — nothing here needs their attention.
  - `has_more` boolean, required: Whether more records matched than were returned. Narrow the query to see them.
  - `next_cursor` string, nullable, required: Always null — search results are not paginated; refine the query.

## 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)