---
title: "List a family’s version history"
method: GET
path: "/v1/workspaces/{workspaceId}/families/{id}/history"
tags: ["Families"]
---

# List a family’s version history

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

## Request

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

Return the seed family’s version history (versions after the original upload), newest first, keyset-paginated by (created_at, id). The seed family is resolved like the family GET — a cross-workspace, cross-firm, missing, or unmatched seed returns 404 (no existence disclosure). A family with no revisions returns an empty list.

## Path parameters

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

## Query parameters

- `cursor` string
- `limit` string

## Response `200`

Family version history

- ExternalFamilyHistoryListResponse: Cursor-paginated family version history (newest first; excludes the original upload)
  - `response` object, required
    - `data` ExternalFamilyVersionDto[], required
      - `id` string, uuid, required
      - `family_id` string, uuid, required
      - `version_number` integer, required
      - `is_current` boolean, required
      - `name` string, required
      - `category` string, required
      - `parent_category` string, required
      - `revit_version` string, required
      - `thumbnail_url` string, nullable, required
      - `change_message` string, nullable, required
      - `uploaded_by` object, nullable, required
        - `type` 'user', required
        - `user_id` string, uuid, required
        - `name` string, required
      - `created_at` string, date-time, required
    - `next_cursor` string, nullable, 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)