/opentargets_database

name: opentargets-database
description: >
  Query Open Targets Platform for target-disease associations, drug target
  discovery, tractability/safety data, genetics/omics evidence, known drugs,
  for therapeutic target identification.

Open Targets Database Skill

Overview

This skill provides access to the Open Targets Platform GraphQL API. It aggregates multi-modal evidence from genetics (GWAS/eQTL), pathways, animal models, and clinical trials to rank target-disease associations and identify druggable genes.

Prerequisites

1. **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure `uv` is installed and on PATH. 2. **User Notification**: If .licenses/opentargets_database_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://platform-docs.opentargets.org/licence, then (2) create the file recording the notification text and timestamp.

Core Rules

• **Use the Wrapper**: ALWAYS execute the provided helper scripts to query the

database rather than accessing the database directly. The scripts automatically enforce fair use and implement retry logic.

• **Output Flag**: The `--output` flag is always required as output can be

very large. Use `jq` or write your own code to process this JSON file.

• **Notification**: If this skill is used, ensure this is mentioned in the

output.

Quick Reference

Always use the provided Python script `scripts/query_opentargets.py` to quickly query the database. It handles API communication, retries, formatting, and automatically truncates overly large responses. NEVER write your own curl or similar requests.

**Usage:**

uv run scripts/query_opentargets.py --output /tmp/opentargets_results.json [OPTIONS] COMMAND [ARGS]...

**Common Options:**

• `--output PATH`: **Required**. Path to write the JSON output file.
• `--limit N`: Limit the number of items returned in arrays (default is 50).

Use a smaller number like 10 when doing preliminary exploration.

• `--page-size N`: Set the API pagination size (default is 200). Increase if

you need more results (e.g., a study with many credible sets).

**Available Commands:**

• **`get-gwas-studies`** *`disease_id`*: Fetches all GWAS studies associated

with a specific disease ID (e.g. `MONDO_0008383` for Rheumatoid Arthritis).

• **`get-study-credible-sets`** *`study_id`*: Fetches all credible sets for a

given study ID (e.g. `FINNGEN_R12_RX_CROHN_2NDLINE`). Returns confidence, finemapping method, variant, and p-value info.

• **`get-qtl-credible-sets`** *`variant_id`*: Retrieves QTL credible sets for

a specific variant ID (e.g. `19_44908822_C_T`).

• **`get-l2g`** *`variant_id [--study-id ID]`*: Returns Locus-to-Gene (L2G)

predictions/scores for a locus to identify the most likely causal gene. Only `variant_id` is required; use `--study-id` to filter to a specific study. Accepts `chr` prefix (e.g. `chr1_113834946_A_G`).

• **`get-target-druggability`** *`ensembl_id`*: Provides tractability data

(small molecule, antibody, etc.) and clinical trial safety info for a gene/target.

• **`get-associated-targets`** *`disease_id`*: Find all target genes

associated with a specific disease ID (EFO or MONDO).

• **`get-disease-drugs`** *`disease_id [--min-stage STAGE]`*: Find all drugs

and clinical candidates associated with a disease. Use `--min-stage` to filter (e.g., `PHASE_3` for Phase III or Approved).

• **`get-associated-diseases`** *`ensembl_id`*: Find all diseases associated

with a specific target Ensembl ID.

• **`search-disease`** *`query_string`*: Search for a disease by name to find

its ID and other metadata.

• **`get-credible-sets-near-target`** *`ensembl_id [--window N]`*: Fetches

credible sets for a target and filters them to those within a genomic window around the target. Useful for finding variants "nearby" a gene.

• **`custom-query`** *`query [--variables '{}']`*: Run a raw GraphQL query for

any other Open Targets data.

L2G Query Usage

The `get-l2g` command has two modes:

• **Variant only** (`get-l2g <variant_id>`): Returns L2G predictions from

**all credible sets across all studies** where that variant is the lead variant. This can return a large number of results (e.g., hundreds). Use this when the user wants a broad view of which gene is most likely causal at a locus, or when no specific study is mentioned.

• **Variant + study** (`get-l2g <variant_id> --study-id <study_id>`): Returns

L2G predictions only for credible sets from that specific study. Use this when the user asks about a specific GWAS study or when you need to narrow down the results.

> **Incomplete results warning:** The variant-only mode can return hundreds of > credible sets. The default `--page-size` is 200, so if the API reports a > `count` higher than the number of `rows` returned, **you are seeing incomplete > results**. Always compare `count` to the actual number of rows. If they > differ, either increase `--page-size` or inform the user that only a subset > was retrieved.

Querying by Region

To find studies with variants "nearby" a gene, use `get-credible-sets-near-target`, which improves upon the base API by performing a flexible search based on genomic position: `uv run scripts/query_opentargets.py --output /tmp/results.json get-credible-sets-near-target ENSG00000156515 --window 500000`

Note that the Open Targets GraphQL schema includes a `regions` parameter for `credibleSets`, however it performs an exact match against pre-computed region strings (e.g., `chr10:68769984-69903496`) and there is some missing data. Use get-credible-sets-near-target as it allows a genomic range overlap search.

This fetches credible sets associated with the target and filters them in Python based on the variant's genomic position.

Advanced GraphQL