---
title: "Get a workspace family by ID"
method: GET
path: "/v1/workspaces/{workspaceId}/families/{id}"
tags: ["Families"]
---

# Get a workspace family by ID

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

## Request

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

Retrieve a single family (current version) scoped to the workspace. A family in another workspace, an archived/missing family, and a family no granted filter matches all return 404 (indistinguishable — no existence disclosure).

## Path parameters

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

## Response `200`

Family found

- ExternalFamilyResponse: Single family resource
  - `response` object, required: Family metadata for external API consumers
    - `id` string, uuid, required
    - `current_version_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
    - `notes` string, nullable, required
    - `is_downloadable` boolean, required
    - `read_only` boolean, required
    - `status` 'processing' | 'ready' | 'failed', required
    - `failure_reason` string, nullable, required
    - `change_message` string, nullable, required
    - `file_size` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, 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`: 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)