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

# List Relationships for a Concept

> Retrieve all relationships for a specific OMOP concept - Maps to, Is a, ingredient of, and vocabulary-specific links for crosswalk analysis.

This endpoint provides relationship information for a concept, showing how it connects to other concepts through various relationship types such as "Is a", "Part of", "Has ingredient", and others in medical vocabularies.

## Path Parameters

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

  <br />

  **Example:** `201826` (Type 2 diabetes mellitus)
</ParamField>

## Query Parameters

<ParamField query="relationship_ids" type="string" optional>
  Comma-separated list of relationship IDs to filter by

  <br />

  **Example:** `Is a,Maps to,Has finding site`
</ParamField>

<ParamField query="vocabulary_ids" type="string" optional>
  Filter relationships to specific vocabularies

  <br />

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

<ParamField query="domain_ids" type="string" optional>
  Filter related concepts to specific domains

  <br />

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

<ParamField query="standard_only" type="boolean" optional default="false">
  Only return relationships to standard concepts
</ParamField>

<ParamField query="include_invalid" type="boolean" optional default="true">
  Include relationships to deprecated/invalid concepts
</ParamField>

<ParamField query="include_reverse" type="boolean" optional default="false">
  Include reverse relationships (where this concept is concept\_id\_2)
</ParamField>

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

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

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

  <br />

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

## Response

<ResponseField name="relationships" type="array">
  Array of relationship objects

  <Expandable title="Relationship Object">
    <ResponseField name="concept_id_1" type="integer">
      Source concept ID (the concept you queried)
    </ResponseField>

    <ResponseField name="concept_id_2" type="integer">
      Target concept ID (the related concept)
    </ResponseField>

    <ResponseField name="relationship_id" type="string">
      Relationship type identifier (e.g., "Is a", "Maps to")
    </ResponseField>

    <ResponseField name="relationship_name" type="string">
      Display name of the relationship
    </ResponseField>

    <ResponseField name="reverse_relationship_id" type="string">
      Reverse relationship identifier (e.g., "Subsumes" for "Is a")
    </ResponseField>

    <ResponseField name="concept_1" type="object">
      Full details of the source concept

      <Expandable title="Concept Object">
        <ResponseField name="concept_id" type="integer">Concept identifier</ResponseField>
        <ResponseField name="concept_name" type="string">Concept name</ResponseField>
        <ResponseField name="concept_code" type="string">Original vocabulary code</ResponseField>
        <ResponseField name="vocabulary_id" type="string">Vocabulary identifier</ResponseField>
        <ResponseField name="vocabulary_name" type="string">Vocabulary display name</ResponseField>
        <ResponseField name="domain_id" type="string">Domain classification</ResponseField>
        <ResponseField name="concept_class_id" type="string">Concept class</ResponseField>
        <ResponseField name="standard_concept" type="string">Standard concept flag (S, C, or null)</ResponseField>
        <ResponseField name="valid_start_date" type="string">Validity start date</ResponseField>
        <ResponseField name="valid_end_date" type="string">Validity end date</ResponseField>
        <ResponseField name="invalid_reason" type="string">Reason if invalid (null if valid)</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="concept_2" type="object">
      Full details of the target concept (same structure as concept\_1)
    </ResponseField>

    <ResponseField name="valid_start_date" type="string">
      Date when relationship became valid
    </ResponseField>

    <ResponseField name="valid_end_date" type="string">
      Date when relationship becomes invalid
    </ResponseField>

    <ResponseField name="invalid_reason" type="string">
      Reason if relationship is invalid (null if valid)
    </ResponseField>
  </Expandable>
</ResponseField>

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

  <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 relationships</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>

    <ResponseField name="request_id" type="string">Unique request identifier</ResponseField>
    <ResponseField name="timestamp" type="string">Request timestamp</ResponseField>
    <ResponseField name="vocab_release" type="string">Vocabulary release version used</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -G "https://api.omophub.com/v1/concepts/201826/relationships" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode "relationship_ids=Is a,Maps to" \
    --data-urlencode "page_size=50"
  ```

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

  concept_id = 201826
  url = f"https://api.omophub.com/v1/concepts/{concept_id}/relationships"
  params = {
      "relationship_ids": "Is a,Maps to",
      "vocabulary_ids": "SNOMED",
      "page_size": 50
  }

  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  response = requests.get(url, params=params, headers=headers)
  data = response.json()

  print(f"Total relationships: {data['meta']['pagination']['total_items']}")
  for rel in data['data']['relationships']:
      print(f"  {rel['relationship_id']}: {rel['concept_2']['concept_name']}")
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    'relationship_ids': 'Is a,Maps to',
    'page_size': '50'
  });

  const response = await fetch(
    `https://api.omophub.com/v1/concepts/201826/relationships?${params}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const data = await response.json();
  console.log(`Found ${data.meta.pagination.total_items} relationships`);
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "relationships": [
        {
          "concept_id_1": 201826,
          "concept_id_2": 73211009,
          "relationship_id": "Is a",
          "relationship_name": "Is a",
          "reverse_relationship_id": "Subsumes",
          "concept_1": {
            "concept_id": 201826,
            "concept_name": "Type 2 diabetes mellitus",
            "concept_code": "44054006",
            "vocabulary_id": "SNOMED",
            "vocabulary_name": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "valid_start_date": "2002-01-31",
            "valid_end_date": "2099-12-31",
            "invalid_reason": null
          },
          "concept_2": {
            "concept_id": 73211009,
            "concept_name": "Diabetes mellitus",
            "concept_code": "73211009",
            "vocabulary_id": "SNOMED",
            "vocabulary_name": "SNOMED",
            "domain_id": "Condition",
            "concept_class_id": "Clinical Finding",
            "standard_concept": "S",
            "valid_start_date": "2002-01-31",
            "valid_end_date": "2099-12-31",
            "invalid_reason": null
          },
          "valid_start_date": "2002-01-31",
          "valid_end_date": "2099-12-31",
          "invalid_reason": null
        }
      ]
    },
    "meta": {
      "request_id": "req_abc123",
      "timestamp": "2025-01-04T10:30:00Z",
      "vocab_release": "2025.1",
      "version": "2025.1",
      "duration": 45,
      "pagination": {
        "page": 1,
        "page_size": 100,
        "total_items": 47,
        "total_pages": 1,
        "has_next": false,
        "has_previous": false
      }
    }
  }
  ```
</ResponseExample>

## Usage Examples

### All Relationships

Get all relationships for a concept:

```bash theme={null}
curl "https://api.omophub.com/v1/concepts/201826/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Hierarchical Relationships Only

Retrieve only "Is a" relationships:

```bash theme={null}
curl "https://api.omophub.com/v1/concepts/201826/relationships?relationship_ids=Is%20a" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Cross-Vocabulary Mappings

Find mappings to ICD-10:

```bash theme={null}
curl "https://api.omophub.com/v1/concepts/201826/relationships?relationship_ids=Maps%20to&vocabulary_ids=ICD10CM" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Including Reverse Relationships

Include relationships where this concept is the target:

```bash theme={null}
curl "https://api.omophub.com/v1/concepts/201826/relationships?include_reverse=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Related Endpoints

* [Get Relationship Types](/api-reference/relationships/get-relationship-types) - Available relationship types
* [Get Concept Ancestors](/api-reference/hierarchy/get-concept-ancestors) - Hierarchical parent relationships
* [Get Concept Descendants](/api-reference/hierarchy/get-concept-descendants) - Hierarchical child relationships
* [Get Concept Mappings](/api-reference/mappings/get-concept-mappings) - Cross-vocabulary mappings

## Notes

* Relationships are bidirectional in the database; use `include_reverse=true` to see both directions
* Standard concepts are not filtered by default; use `standard_only=true` to filter
* Large concepts may have hundreds of relationships - use pagination appropriately
* The response includes full concept details for both source and target concepts