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

# Batch Hierarchy Queries

> Run multiple OMOP concept hierarchy lookups in a single batched request to efficiently retrieve ancestors and descendants for bulk ETL workflows.

## Overview

This endpoint allows you to perform multiple hierarchy queries (ancestors, descendants, or full hierarchy) for multiple concepts in a single API call. This is highly efficient for applications that need hierarchical information for many concepts simultaneously.

## Request Body

**queries** `array` *required*

Array of hierarchy query requests (1-100 queries)

**queries**

**query\_id** `string` *required*

Unique identifier for this query (used to match results)

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

The OMOP concept ID to query hierarchy for

**operation** `string` *required*

Type of hierarchy query. Options: `ancestors`, `descendants`, `hierarchy`, `level`

Any other value fails that individual query with `Unknown operation: <name>`
(the surrounding batch still succeeds - check `success` on each result).
Relationship traversal is not available here; 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).

**params** `object`

Optional parameters for the query

**params**

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

Maximum number of hierarchy levels to traverse

**relationship\_types** `array`

Accepted for backwards compatibility, but **ignored by every operation this
endpoint supports**.

All four operations read OMOP's precomputed `concept_ancestor` closure,
which stores transitive `Is a` subsumption only and has no relationship
column to filter on. Passing `Part of` - or a nonexistent relationship -
returns the same `Is a` results.

**vocabulary\_ids** `array`

Limit results to specific vocabularies

**domain\_ids** `array`

Limit results to specific domains

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

Include relationships to invalid/deprecated concepts

## Query Parameters

**vocab\_release** `string`

Specific vocabulary release version (e.g., "2025.1")

## Response

**success** `boolean` *required*

Indicates whether the request was successful

**data** `array` *required*

Array of query results matching the input order

**data**

**query\_id** `string`

The query identifier from the request

**concept\_id** `integer`

The concept ID that was queried

**operation** `string`

The operation that was performed

**success** `boolean`

Whether this individual query succeeded

**results** `object | array`

Result data if the query succeeded (structure varies by operation)

**results (hierarchy)**

**ancestors** `array`

Array of ancestor concepts (for ancestors/hierarchy operations)

**concept object**

**concept\_id** `integer`

OMOP concept ID

**concept\_name** `string`

Primary concept name

**vocabulary\_id** `string`

Source vocabulary identifier

**domain\_id** `string`

Clinical domain classification

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

Concept class identifier

**standard\_concept** `string|null`

Standard concept flag (S, C, or null)

**level** `integer`

Distance from the source concept in hierarchy

**descendants** `array`

Array of descendant concepts (for descendants/hierarchy operations)

**concept object**

**concept\_id** `integer`

OMOP concept ID

**concept\_name** `string`

Primary concept name

**vocabulary\_id** `string`

Source vocabulary identifier

**domain\_id** `string`

Clinical domain classification

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

Concept class identifier

**standard\_concept** `string|null`

Standard concept flag (S, C, or null)

**level** `integer`

Distance from the source concept in hierarchy

**total\_count** `integer`

Total number of results

**error** `string`

Error message if the query failed

**meta** `object` *required*

Response metadata

**meta**

**request\_id** `string`

Unique request identifier

**timestamp** `string`

ISO 8601 timestamp

**vocab\_release** `string`

Vocabulary release version used

```bash cURL theme={null}
curl -X POST "https://api.omophub.com/v1/concepts/hierarchy/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "query_id": "q1",
        "concept_id": 201826,
        "operation": "ancestors",
        "params": {
          "max_levels": 5
        }
      },
      {
        "query_id": "q2",
        "concept_id": 4182210,
        "operation": "descendants",
        "params": {
          "max_levels": 3
        }
      },
      {
        "query_id": "q3",
        "concept_id": 313217,
        "operation": "hierarchy",
        "params": {
          "max_levels": 4,
          "relationship_types": ["Is a"]
        }
      }
    ]
  }'
```

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

def batch_hierarchy_query(queries, api_key):
    url = "https://api.omophub.com/v1/concepts/hierarchy/batch"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    data = {"queries": queries}

    response = requests.post(url, json=data, headers=headers)
    return response.json()

# Example usage
queries = [
    {
        "query_id": "diabetes",
        "concept_id": 201826,
        "operation": "ancestors",
        "params": {"max_levels": 5}
    },
    {
        "query_id": "hypertension",
        "concept_id": 4182210,
        "operation": "descendants",
        "params": {"max_levels": 3}
    },
    {
        "query_id": "afib",
        "concept_id": 313217,
        "operation": "hierarchy",
        "params": {"max_levels": 4}
    }
]

result = batch_hierarchy_query(queries, "YOUR_API_KEY")

for query_result in result['data']:
    if query_result['success']:
        query_data = query_result['results']
        if isinstance(query_data, list):
            ancestors = len(query_data) if query_result['operation'] == 'ancestors' else 0
            descendants = len(query_data) if query_result['operation'] == 'descendants' else 0
        else:
            ancestors = len(query_data.get('ancestors', []))
            descendants = len(query_data.get('descendants', []))
        print(f"{query_result['query_id']}: {ancestors} ancestors, {descendants} descendants")
    else:
        print(f"{query_result['query_id']}: Error - {query_result['error']}")
```

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

// Not yet exposed as a dedicated SDK method - use the typed low-level helper
// for parity with auth, retries, and error handling.
const client = new OMOPHub();

interface HierarchyQueryResult {
  query_id: string;
  concept_id: number;
  operation: 'ancestors' | 'descendants' | 'hierarchy' | 'level';
  success: boolean;
  results?: unknown[] | { ancestors?: unknown[]; descendants?: unknown[] };
  error?: string;
}

const { data } = await client.post<HierarchyQueryResult[]>(
  '/concepts/hierarchy/batch',
  {
    queries: [
      {
        query_id: 'q1',
        concept_id: 201826,
        operation: 'ancestors',
        params: { max_levels: 5 },
      },
      {
        query_id: 'q2',
        concept_id: 4182210,
        operation: 'descendants',
        params: { max_levels: 3 },
      },
      {
        query_id: 'q3',
        concept_id: 313217,
        operation: 'hierarchy',
        params: { max_levels: 4 },
      },
    ],
  }
);

data?.forEach(queryResult => {
  if (queryResult.success) {
    const result = queryResult.results;
    const ancestors =
      queryResult.operation === 'ancestors' && Array.isArray(result)
        ? result.length
        : !Array.isArray(result)
          ? (result?.ancestors?.length ?? 0)
          : 0;
    const descendants =
      queryResult.operation === 'descendants' && Array.isArray(result)
        ? result.length
        : !Array.isArray(result)
          ? (result?.descendants?.length ?? 0)
          : 0;
    console.log(
      `${queryResult.query_id}: ${ancestors} ancestors, ${descendants} descendants`
    );
  } else {
    console.error(`${queryResult.query_id} failed: ${queryResult.error}`);
  }
});
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "query_id": "q1",
      "concept_id": 201826,
      "operation": "ancestors",
      "success": true,
      "results": [
        {
          "concept_id": 201826,
          "concept_name": "Type 2 diabetes mellitus",
          "concept_code": "44054006",
          "vocabulary_id": "SNOMED",
          "vocabulary_name": "SNOMED CT",
          "domain_id": "Condition",
          "concept_class_id": "Clinical Finding",
          "standard_concept": "S",
          "level": 0,
          "min_levels_of_separation": 0,
          "max_levels_of_separation": 0,
          "relationship_id": "Is a",
          "relationship_name": "Is a",
          "valid_start_date": "1970-01-01T00:00:00.000Z",
          "valid_end_date": "2099-12-31T00:00:00.000Z",
          "invalid_reason": null
        }
      ]
    }
  ],
  "meta": {
    "request_id": "req_batch_hierarchy_123",
    "timestamp": "2024-12-22T10:00:00Z",
    "vocab_release": "2025.1"
  }
}
```

## Usage Examples

### Simple Batch Ancestors

Get ancestors for multiple concepts:

```json theme={null}
{
  "queries": [
    { "query_id": "q1", "concept_id": 201826, "operation": "ancestors" },
    { "query_id": "q2", "concept_id": 4182210, "operation": "ancestors" },
    { "query_id": "q3", "concept_id": 313217, "operation": "ancestors" }
  ]
}
```

### Mixed Operations

Combine different operations in one batch:

```json theme={null}
{
  "queries": [
    {
      "query_id": "ancestors_query",
      "concept_id": 201826,
      "operation": "ancestors",
      "params": { "max_levels": 5 }
    },
    {
      "query_id": "descendants_query",
      "concept_id": 4182210,
      "operation": "descendants",
      "params": { "max_levels": 3 }
    },
    {
      "query_id": "full_hierarchy",
      "concept_id": 313217,
      "operation": "hierarchy",
      "params": { "max_levels": 4 }
    }
  ]
}
```

### With Filtering

Use vocabulary and relationship filters:

```json theme={null}
{
  "queries": [
    {
      "query_id": "filtered_query",
      "concept_id": 201826,
      "operation": "hierarchy",
      "params": {
        "max_levels": 5,
        "relationship_types": ["Is a"],
        "vocabulary_ids": ["SNOMED", "ICD10CM"]
      }
    }
  ]
}
```

## Important Notes

* **Batch size limit**: Maximum 100 queries per batch request
* **Performance optimization**: Batch processing is significantly faster than individual requests
* **Error handling**: Individual query failures don't affect other queries in the batch
* **Result matching**: Use `query_id` to match results to your input queries
* **Rate limiting**: Batch requests count as single requests for rate limiting purposes

## Related Endpoints

* [Get Concept Ancestors](https://docs.omophub.com/api-reference/concepts/get-concept-ancestors) - Single concept ancestors
* [Get Concept Descendants](https://docs.omophub.com/api-reference/concepts/get-concept-descendants) - Single concept descendants
* [Get Concept Hierarchy](https://docs.omophub.com/api-reference/concepts/get-concept-hierarchy) - Complete hierarchy tree


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