> ## 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 Ancestors

> Retrieve all ancestor OMOP concepts for a given concept - hierarchical context, classification paths, and parent terms for concept set expansion.

This endpoint returns the complete ancestor hierarchy for a specific concept, including parent concepts, grandparents, and all higher-level classifications up to the root of the vocabulary hierarchy.

## Path Parameters

**concept\_id** `integer` *required*

The unique identifier of the concept to retrieve ancestors for

**Example:** `201826` (Type 2 diabetes mellitus)

## Query Parameters

**vocabulary\_ids** `string`

Filter ancestors to specific vocabularies (comma-separated)

**Example:** `SNOMED,ICD10CM`

**domain\_ids** `string`

Filter ancestors to specific domains (comma-separated)

**Example:** `Condition,Observation`

**max\_levels** `integer` (default: 10)

Maximum number of hierarchy levels to traverse

**Range:** `1-20`

> [!WARNING]
>
> **This endpoint always traverses the `Is a` hierarchy.** It reads OMOP's
> precomputed `concept_ancestor` closure, which stores only transitive `Is a`
> ancestry - it has no relationship column to filter on. Every ancestor is
> therefore returned with `relationship_id: "Is a"`.
>
> A `relationship_types` parameter is accepted for backwards compatibility but has
> **no effect here**: passing `Part of`, or even a nonexistent relationship, returns
> the same `Is a` ancestors. To traverse other relationship types, use
> [`GET /v1/concepts/{concept_id}/relationships`](https://docs.omophub.com/api-reference/relationships/get-concept-relationships)
> or [`POST /v1/concepts/relationships/traverse`](https://docs.omophub.com/api-reference/concepts/traverse-relationships),
> which query `concept_relationship` directly.

**include\_distance** `boolean` (default: false)

Include `hierarchy_level` field for each ancestor (distance from source
concept)

**include\_paths** `boolean` (default: false)

Include `path_length` field for each ancestor

**include\_invalid** `boolean` (default: false)

Include deprecated/invalid concepts in ancestry (by default they are excluded)

**page** `integer` (default: 1)

Page number for pagination (1-based)

**max\_results** `integer` (default: 5000)

Maximum size of the ancestor set to retrieve before pagination is applied.

**Range:** `1-5000`

Defaults to the maximum, so paging through the response returns every ancestor
**that matches this request** - those within `max_levels` and any
`vocabulary_ids` / `domain_ids` filters you supplied. (`relationship_types` is
not applied - see above.) It is not necessarily the concept's entire ancestry:
`max_levels` defaults to `10`, so more distant ancestors are excluded, and
`truncated` does **not** flag that (it reports the row cap only). Pass
`max_levels=20` if you need the full ancestry.

Results are ordered by ascending `min_levels_of_separation`. When
`max_results` truncates the set, the nearest ancestors - direct parents before
grandparents and roots - are preserved. Concepts at the same separation have
no semantic precedence over one another.

**page\_size** `integer` (default: 100)

Number of ancestor concepts to return per page. Values above `200` are clamped
to `200`.

**vocab\_release** `string`

Specific vocabulary release version to query

**Example:** `2025.1`

## Response

**success** `boolean`

Whether hierarchy retrieval completed.

**data** `object`

Source concept and ancestor list.

**concept\_id** `integer`

The concept ID for which ancestors were retrieved

**concept\_name** `string`

Standard name of the source concept

**vocabulary\_id** `string`

Vocabulary containing the source concept

**ancestors** `array`

Array of ancestor concepts in hierarchical order

**Ancestor Concept Object**

**concept\_id** `integer`

Unique identifier for the ancestor concept

**concept\_name** `string`

Standard name of the ancestor concept

**concept\_code** `string`

Original code from the vocabulary

**vocabulary\_id** `string`

Vocabulary containing this ancestor concept

**vocabulary\_name** `string`

Human-readable vocabulary name

**domain\_id** `string`

Domain classification of the ancestor

**concept\_class\_id** `string`

Concept class identifier

**standard\_concept** `string`

Standard concept designation ('S', 'C', or null)

**level** `integer`

Distance from source concept (always present)

**min\_levels\_of\_separation** `integer`

Minimum levels of separation from source concept

**max\_levels\_of\_separation** `integer`

Maximum levels of separation from source concept

**relationship\_id** `string`

Relationship type ID (e.g., "Is a")

**relationship\_name** `string`

Relationship type name (e.g., "Is a")

**hierarchy\_level** `integer`

Distance from source concept (only when include\_distance=true, same as level)

**path\_length** `integer`

Path length from source concept (only when include\_paths=true, same as level)

**valid\_start\_date** `string`

Date when concept became valid (ISO format)

**valid\_end\_date** `string`

Date when concept became invalid (ISO format)

**invalid\_reason** `string`

Reason for concept invalidation if applicable

**hierarchy\_summary** `object`

Summary statistics about the ancestor hierarchy

**Hierarchy Summary Object**

**total\_ancestors** `integer`

Total number of ancestor concepts found

**max\_hierarchy\_depth** `integer`

Maximum depth of the hierarchy tree

**unique\_vocabularies** `array`

List of vocabulary IDs represented in ancestors

**relationship\_types\_used** `array`

List of relationship type IDs found in hierarchy

**truncated** `boolean`

Whether the matching ancestor set exceeded `result_limit` and was cut
off before pagination. This reports only the row cap; `max_levels` and
vocabulary/domain filters can also narrow the result without setting it.

**result\_limit** `integer`

The `max_results` cap applied before pagination.

**meta** `object`

Response metadata and pagination information

**Metadata Object**

**pagination** `object`

**page** `integer`

Current page number

**page\_size** `integer`

Items per page

**total\_items** `integer`

Total ancestor concepts

**total\_pages** `integer`

Total number of pages

**has\_next** `boolean`

Whether next page exists

**has\_previous** `boolean`

Whether previous page exists

**request\_id** `string`

Request correlation identifier.

**timestamp** `string`

ISO 8601 response timestamp.

**vocab\_release** `string`

Vocabulary release used for the query.

```bash cURL theme={null}
curl -X GET "https://api.omophub.com/v1/concepts/201826/ancestors?include_paths=true&include_distance=true&max_levels=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```ts TypeScript theme={null}
import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
const { data: ancestorData } = await client.hierarchy.ancestors(201826, {
  includePaths: true,
  includeDistance: true,
  maxLevels: 5,
});

console.log(
  `Found ${ancestorData?.hierarchy_summary.total_ancestors} ancestors`
);
console.log('First ancestor:', ancestorData?.ancestors[0]?.concept_name);
```

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

concept_id = 201826  # Type 2 diabetes mellitus
url = f"https://api.omophub.com/v1/concepts/{concept_id}/ancestors"
params = {
    "include_paths": True,
    "include_distance": True,
    "max_levels": 5
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

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

print(f"Concept: {ancestor_data['data']['concept_name']}")
print(f"Total ancestors: {ancestor_data['data']['hierarchy_summary']['total_ancestors']}")

for ancestor in ancestor_data['data']['ancestors'][:5]:
    level = ancestor.get('level', 'Unknown')
    print(f"Level {level}: {ancestor['concept_name']} ({ancestor['concept_id']})")
```

```json theme={null}
{
  "success": true,
  "data": {
    "concept_id": 201826,
    "concept_name": "Type 2 diabetes mellitus",
    "vocabulary_id": "SNOMED",
    "ancestors": [
      {
        "concept_id": 73211009,
        "concept_name": "Diabetes mellitus",
        "concept_code": "73211009",
        "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": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 1,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "concept_id": 362969004,
        "concept_name": "Disorder of endocrine system",
        "concept_code": "362969004",
        "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": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 2,
        "valid_start_date": "2002-01-31",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      },
      {
        "concept_id": 64572001,
        "concept_name": "Disease",
        "concept_code": "64572001",
        "vocabulary_id": "SNOMED",
        "vocabulary_name": "SNOMED Clinical Terms",
        "domain_id": "Condition",
        "concept_class_id": "Clinical Finding",
        "standard_concept": "S",
        "level": 3,
        "min_levels_of_separation": 3,
        "max_levels_of_separation": 3,
        "relationship_id": "Is a",
        "relationship_name": "Is a",
        "hierarchy_level": 3,
        "valid_start_date": "1970-01-01",
        "valid_end_date": "2099-12-31",
        "invalid_reason": null
      }
    ],
    "hierarchy_summary": {
      "total_ancestors": 3,
      "max_hierarchy_depth": 3,
      "unique_vocabularies": ["SNOMED"],
      "relationship_types_used": ["Is a"],
      "truncated": false,
      "result_limit": 5000
    }
  },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    },
    "request_id": "req_ancestors_201826_20250104_103100",
    "timestamp": "2025-01-04T10:31:00Z",
    "vocab_release": "2025.1"
  }
}
```

## Usage Examples

### Basic Ancestor Retrieval

Get all ancestors for a specific concept:

```ts TypeScript theme={null}
const { data: ancestors } = await client.hierarchy.ancestors(201826);
```

### Limited Hierarchy Depth

Retrieve ancestors up to a specific number of levels:

```ts TypeScript theme={null}
const { data: nearAncestors } = await client.hierarchy.ancestors(201826, {
  maxLevels: 3,
});
```

### Classification Path Analysis

Get complete classification paths from concept to root:

```ts TypeScript theme={null}
const { data: pathData } = await client.hierarchy.ancestors(201826, {
  includePaths: true,
  includeDistance: true,
});
```

### Cross-Vocabulary Hierarchy

Analyze ancestors within specific vocabulary:

```ts TypeScript theme={null}
const { data: snomedAncestors } = await client.hierarchy.ancestors(201826, {
  vocabularyIds: ['SNOMED'],
});
```

### Multiple Relationship Types

Follow different types of hierarchical relationships:

```ts TypeScript theme={null}
const { data: extendedHierarchy } = await client.hierarchy.ancestors(201826, {
  relationshipTypes: ['Is a', 'Part of'],
});
```

## Related Endpoints

* [Get Concept Descendants](https://docs.omophub.com/api-reference/hierarchy/get-concept-descendants.md) - Retrieve child concepts
* [Get Concept Hierarchy](https://docs.omophub.com/api-reference/hierarchy/get-concept-hierarchy.md) - Complete hierarchy view
* [Get Concept Relationships](https://docs.omophub.com/api-reference/relationships/get-concept-relationships.md) - All concept relationships
* [Get Concept Details](https://docs.omophub.com/api-reference/concepts/get-concept-details) - Complete concept information

## Notes

* Hierarchy traversal follows "Is a" relationships by default, but can be customized
* Some concepts may have multiple classification paths to different root concepts
* Cross-vocabulary concepts may have ancestors in different vocabularies
* Standard concepts are prioritized in hierarchy traversal unless explicitly disabled
* Deprecated concepts are excluded from ancestry unless specifically requested
* Maximum hierarchy depth is typically 6-8 levels for most medical vocabularies


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.