Search View Records

Endpoint

POST https://api.parcelengineering.com/api/v1/workspace/views/{id}/records/search

Runs a shared View and returns hydrated records for its dataset. This is the broader View executor — not the book-only entity searches.

• Dynamic: compiles the stored web-filter definition against the workspace-visible browse base for that dataset.
• Static: membership is the base; request filters only narrow the current result.

Request filters and relations use the existing Workspace entity SearchRequest descriptors for that dataset and are ephemeral: they are ANDed onto the View for this call only. They never rewrite the stored Dynamic definition, mark the View dirty, or change Static membership.

The stored Dynamic definition is a different grammar (web FilterState). Presentation sorting is ignored; use an explicit request sort or the dataset default.

Search costs 1 credit per returned row. Requires the same Pro / workspace gates as other Workspace searches.

Caution

The Workspace API requires the Pro plan. A request from a non-Pro workspace or a non-member receives 403 forbidden.

Note

Ordinary POST /workspace/accounts/search, contacts, and projects remain “your book” and do not accept view_id. Use this endpoint (or MCP workspace_search_* with view_id) for View-scoped execution.

Path parameters

Parameter	Description
id	UUID of the View. Unknown or out-of-workspace → 404.

Request body

Same shape as the corresponding Workspace entity search: optional query, filters, sort, limit, offset, search_after. Filter and relational keys match the book endpoints for that dataset.

Sort keys (View-record only)

Dataset	Valid sort fields	Default
Account	name, created_at	name asc
Contact	name, created_at	name asc
Project	last_signal_at, name, created_at	last_signal_at desc

Overlay-only updated_at and atlas_score sorts are book-only. View execution LEFT JOINs overlays, so those values are nullable; keyset pagination cannot advance through a null tail. Book entity searches keep their existing sort enums unchanged.

Example

cURL

Search records in a View

curl -X POST \
  https://api.parcelengineering.com/api/v1/workspace/views/a1b2c3d4-0001-4e8d-bf6a-000000000001/records/search \
  -H "Authorization: Bearer pcl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "city": { "value": "Boston" }
    },
    "sort": { "field": "name", "order": "asc" },
    "limit": 25
  }'

JavaScript

Search records in a View

const response = await fetch(
  'https://api.parcelengineering.com/api/v1/workspace/views/a1b2c3d4-0001-4e8d-bf6a-000000000001/records/search',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pcl_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      filters: { city: { value: 'Boston' } },
      sort: { field: 'name', order: 'asc' },
      limit: 25,
    }),
  }
);

const { data, metadata } = await response.json();

Response

Response

{
  "data": {
    "dataset": "account",
    "records": [
      {
        "id": "8a1f3c2e-0001-4b7d-9e5a-000000000001",
        "name": "Acme Development Group",
        "account_types": ["developer"],
        "icp_tier": "tier_1",
        "atlas_score": 87,
        "workspace_status": "active",
        "tags": ["boston"],
        "updated_at": "2026-07-01T12:00:00.000Z"
      }
    ]
  },
  "metadata": {
    "total": 4,
    "total_is_capped": false,
    "limit": 25,
    "offset": 0,
    "search_after": null,
    "credits": 4
  }
}

Workspace overlay fields may be null when the record is View-visible but not in the book. Page size is 1–100. Totals use the same cap as other searches.

See Workspace Views for definition vs request-filter grammar.