> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Concept Descendants

> Retrieve all descendant OMOP concepts for a given concept - hierarchical children and specialized terms for phenotype and cohort definitions.

This endpoint returns all descendant concepts (children, grandchildren, etc.) for a specific concept, allowing exploration of more specific terms and sub-classifications within the medical vocabulary hierarchy.

## Path Parameters

<ParamField path="concept_id" type="integer" required>
  The unique identifier of the concept to retrieve descendants for

  <br />

  **Example:** `73211009` (Diabetes mellitus)
</ParamField>

## Query Parameters

<ParamField query="vocabulary_ids" type="string" optional>
  Filter descendants to specific vocabularies (comma-separated)

  <br />

  **Example:** `SNOMED,ICD10CM`
</ParamField>

<ParamField query="domain_ids" type="string" optional>
  Filter descendants to specific domains (comma-separated)

  <br />

  **Example:** `Condition,Drug`
</ParamField>

<ParamField query="max_levels" type="integer" optional default="10">
  Maximum number of hierarchy levels to traverse downward

  <br />

  **Range:** `1-20`
</ParamField>

<ParamField query="relationship_types" type="string" optional>
  Relationship types to follow for hierarchy traversal. Spaces must be URL-encoded (%20) in URLs.

  <br />

  **Default:** `Is a`

  <br />

  **Allowed values:** `Is a`, `Has part`, `Subsumes`, `Part of`, `Has ingredient`, `RxNorm has dose form`

  <br />

  **Example:** `Is%20a,Has%20part` (URL-encoded)
</ParamField>

<ParamField query="include_distance" type="boolean" optional default="false">
  Include `hierarchy_level` field for each descendant (distance from source concept)
</ParamField>

<ParamField query="include_paths" type="boolean" optional default="false">
  Include `path_length` field for each descendant
</ParamField>

<ParamField query="include_invalid" type="boolean" optional default="true">
  Include deprecated/invalid concepts in descendants (default excludes them)
</ParamField>

<ParamField query="page" type="integer" optional default="1">
  Page number for pagination (1-based)
</ParamField>

<ParamField query="page_size" type="integer" optional default="20">
  Number of descendant concepts to return per page (max 1000)
</ParamField>

<ParamField query="vocab_release" type="string" optional>
  Specific vocabulary release version to query

  <br />

  **Example:** `2025.1`
</ParamField>

## Response

<ResponseField name="concept_id" type="integer">
  The concept ID for which descendants were retrieved
</ResponseField>

<ResponseField name="concept_name" type="string">
  Standard name of the source concept
</ResponseField>

<ResponseField name="vocabulary_id" type="string">
  Vocabulary containing the source concept
</ResponseField>

<ResponseField name="descendants" type="array">
  Array of descendant concepts in hierarchical order

  <Expandable title="Descendant Concept Object">
    <ResponseField name="concept_id" type="integer">
      Unique identifier for the descendant concept
    </ResponseField>

    <ResponseField name="concept_name" type="string">
      Standard name of the descendant concept
    </ResponseField>

    <ResponseField name="concept_code" type="string">
      Original code from the vocabulary
    </ResponseField>

    <ResponseField name="vocabulary_id" type="string">
      Vocabulary containing this descendant concept
    </ResponseField>

    <ResponseField name="vocabulary_name" type="string">
      Human-readable vocabulary name
    </ResponseField>

    <ResponseField name="domain_id" type="string">
      Domain classification of the descendant
    </ResponseField>

    <ResponseField name="concept_class_id" type="string">
      Concept class identifier
    </ResponseField>

    <ResponseField name="standard_concept" type="string">
      Standard concept designation ('S', 'C', or null)
    </ResponseField>

    <ResponseField name="level" type="integer">
      Distance from source concept (always present)
    </ResponseField>

    <ResponseField name="min_levels_of_separation" type="integer">
      Minimum levels of separation from source concept
    </ResponseField>

    <ResponseField name="max_levels_of_separation" type="integer">
      Maximum levels of separation from source concept
    </ResponseField>

    <ResponseField name="relationship_id" type="string">
      Relationship type ID (e.g., "Subsumes")
    </ResponseField>

    <ResponseField name="relationship_name" type="string">
      Relationship type name (e.g., "Subsumes")
    </ResponseField>

    <ResponseField name="hierarchy_level" type="integer" optional>
      Distance from source concept (only when include\_distance=true, same as level)
    </ResponseField>

    <ResponseField name="path_length" type="integer" optional>
      Path length from source concept (only when include\_paths=true, same as level)
    </ResponseField>

    <ResponseField name="valid_start_date" type="string">
      Date when concept became valid (ISO format)
    </ResponseField>

    <ResponseField name="valid_end_date" type="string">
      Date when concept became invalid (ISO format)
    </ResponseField>

    <ResponseField name="invalid_reason" type="string" optional>
      Reason for concept invalidation if applicable
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hierarchy_summary" type="object">
  Summary statistics about the descendant hierarchy

  <Expandable title="Hierarchy Summary Object">
    <ResponseField name="total_descendants" type="integer">
      Total number of descendant concepts found
    </ResponseField>

    <ResponseField name="max_hierarchy_depth" type="integer">
      Maximum depth of the descendant tree
    </ResponseField>

    <ResponseField name="unique_vocabularies" type="array">
      List of vocabulary IDs represented in descendants
    </ResponseField>

    <ResponseField name="relationship_types_used" type="array">
      List of relationship type IDs found in hierarchy
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Response metadata and pagination information

  <Expandable title="Metadata Object">
    <ResponseField name="pagination" type="object">
      <ResponseField name="page" type="integer">Current page number</ResponseField>
      <ResponseField name="page_size" type="integer">Items per page</ResponseField>
      <ResponseField name="total_items" type="integer">Total descendant concepts</ResponseField>
      <ResponseField name="total_pages" type="integer">Total number of pages</ResponseField>
      <ResponseField name="has_next" type="boolean">Whether next page exists</ResponseField>
      <ResponseField name="has_previous" type="boolean">Whether previous page exists</ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.omophub.com/v1/concepts/73211009/descendants?include_distance=true&max_levels=3" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  concept_id = 73211009  # Diabetes mellitus
  url = f"https://api.omophub.com/v1/concepts/{concept_id}/descendants"
  params = {
      "include_distance": True,
      "max_levels": 3,
      "page_size": 50
  }

  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, params=params, headers=headers)
  descendant_data = response.json()

  print(f"Concept: {descendant_data['concept_name']}")
  print(f"Total descendants: {descendant_data['hierarchy_summary']['total_descendants']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.omophub.com/v1/concepts/73211009/descendants?include_distance=true&max_levels=3', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const descendantData = await response.json();
  console.log(`Found ${descendantData.hierarchy_summary.total_descendants} descendants`);
  console.log(`Max depth: ${descendantData.hierarchy_summary.max_hierarchy_depth}`);
  ```

  ```bash cURL (filtered by domain) theme={null}
  curl -X GET "https://api.omophub.com/v1/concepts/73211009/descendants?domain_ids=Condition&max_levels=2&page_size=25" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python (with hierarchy grouping) theme={null}
  import requests
  from collections import defaultdict

  concept_id = 73211009
  response = requests.get(
      f"https://api.omophub.com/v1/concepts/{concept_id}/descendants",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"include_distance": True, "max_levels": 3}
  )

  data = response.json()
  by_level = defaultdict(list)

  for desc in data['descendants']:
      level = desc.get('hierarchy_level', 0)
      by_level[level].append(desc['concept_name'])

  for level in sorted(by_level.keys()):
      print(f"Level {level}: {len(by_level[level])} concepts")
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "concept_id": 73211009,
      "concept_name": "Diabetes mellitus",
      "vocabulary_id": "SNOMED",
      "descendants": [
        {
          "concept_id": 44054006,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 1,
          "min_levels_of_separation": 1,
          "max_levels_of_separation": 1,
          "relationship_id": "Subsumes",
          "relationship_name": "Subsumes",
          "hierarchy_level": 1,
          "valid_start_date": "1970-01-01",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null
        },
        {
          "concept_id": 46635009,
          "concept_name": "Type 1 diabetes mellitus",
          "concept_code": "46635009",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 1,
          "min_levels_of_separation": 1,
          "max_levels_of_separation": 1,
          "relationship_id": "Subsumes",
          "relationship_name": "Subsumes",
          "hierarchy_level": 1,
          "valid_start_date": "1970-01-01",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null
        },
        {
          "concept_id": 237599002,
          "concept_name": "Insulin dependent diabetes mellitus",
          "concept_code": "237599002",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED Clinical Terms",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 2,
          "min_levels_of_separation": 2,
          "max_levels_of_separation": 2,
          "relationship_id": "Subsumes",
          "relationship_name": "Subsumes",
          "hierarchy_level": 2,
          "valid_start_date": "2002-01-31",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null
        }
      ],
      "hierarchy_summary": {
        "total_descendants": 847,
        "max_hierarchy_depth": 6,
        "unique_vocabularies": ["SNOMED"],
        "relationship_types_used": ["Subsumes"]
      }
    },
    "meta": {
      "pagination": {
        "page": 1,
        "page_size": 100,
        "total_items": 847,
        "total_pages": 9,
        "has_next": true,
        "has_previous": false
      },
      "request_id": "req_descendants_123",
      "timestamp": "2024-12-22T10:00:00Z",
      "vocab_release": "2025.2"
    }
  }
  ```
</ResponseExample>

## Usage Examples

**Note:** Examples assume a preconfigured client with base URL `https://api.omophub.com` and authentication headers. For direct usage:

```javascript theme={null}
const response = await fetch('https://api.omophub.com/v1/concepts/73211009/descendants', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});
```

### Basic Descendant Retrieval

Get all descendants for a specific concept:

```javascript theme={null}
const descendants = await fetch('/v1/concepts/73211009/descendants');
```

### Limited Hierarchy Depth

Retrieve descendants up to a specific number of levels:

```javascript theme={null}
const nearDescendants = await fetch('/v1/concepts/73211009/descendants?max_levels=2');
```

### Domain-Specific Descendants

Filter descendants to specific medical domains:

```javascript theme={null}
const conditionDescendants = await fetch('/v1/concepts/73211009/descendants?domain_ids=Condition');
```

### Detailed Descendant Information

Get descendants with hierarchy levels and path information:

```javascript theme={null}
const detailedData = await fetch('/v1/concepts/73211009/descendants?include_distance=true&include_paths=true');
```

## Related Endpoints

* [Get Concept Ancestors](/api-reference/hierarchy/get-concept-ancestors) - Retrieve parent concepts
* [Get Concept Hierarchy](/api-reference/hierarchy/get-concept-hierarchy) - Complete hierarchy view
* [Get Concept Relationships](/api-reference/relationships/get-concept-relationships) - All concept relationships
* [Search Concepts](/api-reference/search/basic-search) - Search within specific hierarchies

## Notes

* Descendant traversal follows "Is a" relationships by default, but can include other relationship types
* Large hierarchies may contain thousands of descendants - use pagination and filtering appropriately
* Standard concepts are prioritized unless explicitly disabled
* Some medical concepts may have very deep hierarchies (6+ levels)
* Cross-vocabulary concepts may have descendants from multiple vocabularies
* Deprecated concepts are excluded from descendants unless specifically requested with `include_invalid=true`