---
title: "List families similar to a seed family"
method: GET
path: "/v1/workspaces/{workspaceId}/families/{id}/similar"
tags: ["Families"]
---

# List families similar to a seed family

`GET /v1/workspaces/{workspaceId}/families/{id}/similar`

## Request

- Base URL: `https://external-api.pirros.com`
- URL: `https://external-api.pirros.com/v1/workspaces/{workspaceId}/families/{id}/similar`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.pirros.com/oauth/token`

Return up to 20 families similar to the seed family, ranked by the version-stamped similarity model and scoped to the workspace. The seed family is resolved like the family GET (a cross-firm or missing seed returns 404). limit is 1-20 (default 10) and is rejected, never clamped, when out of range; the response is not paginated (next_cursor is always null). When the seed has no similar families, the response is an empty list with 200 (not 404).

## Path parameters

- `workspaceId` string, uuid, required
- `id` string, uuid, required

## Query parameters

- `limit` string

## Response `200`

Similar families

- ExternalSimilarFamilyResponse: Version-stamped similar families (hard-capped at 20, no pagination)
  - `response` object, required
    - `data` ExternalSimilarFamilyDto[], required
      - `id` string, uuid, required
      - `version_number` integer, required
      - `name` string, required
      - `category` string, required
      - `parent_category` string, required
      - `classification` string, required
      - `revit_version` string, required
      - `project_id` string, uuid, required
      - `similarity_score` number, required
    - `next_cursor` unknown, required
    - `similarity_version` string, required
    - `model_version` string, required
    - `expanded` object, required
  - `meta` object, required
    - `request_id` string, uuid, required

## Other responses

- `400`: Invalid request (bad path param, query param, or cursor)
- `401`: Unauthorized (invalid or missing token)
- `404`: Seed family not found in this workspace
- `429`: Rate limit exceeded (1000 requests per hour per client)
- `503`: External API temporarily disabled by operator kill switch (service_unavailable)

---

[API](https://skmtc.dev/pirros/apis/pirros-external-api.md) - [All operations](https://skmtc.dev/pirros/apis/pirros-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pirros/apis/pirros-external-api/revisions/01c66b8d9fd1?raw)