> For the complete documentation index, see [llms.txt](https://docs.biobox.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biobox.io/guide/how-to/ask-biobox-with-claude/tools/where-entity-ranks.md).

# where\_entity\_ranks — Where entity ranks

Where entity ranks

Where entity ranks

## What it does

Given one entity by its graph-node uuid, show where it ranks across ALL the org's scoring reports — best rank first — so you can see which model gives it its strongest standing. Each ranking carries the reportId + modelId to drill into next (get\_evidence / get\_report\_scores).

**When to use:** the user asks "across our models, where does gene X rank highest?" (e.g. which disease model puts ERBB4 at the top); the user asks "which model / report gives gene X its best score?"; comparing one gene's standing across diseases — to tell a disease-specific signal from a pan-disease one (top in some reports, mid/negative in others).

**When NOT to use:** you only have a NAME, not a uuid — resolve it with search\_entities first (or use search\_models in gene-mode to find models by gene); you want the full ranked list of a SINGLE report (use get\_report\_scores); the user asks WHY the entity scores the way it does — its evidence (use get\_evidence).

**Parameters:**

* `objectId` — the entity's graph-node uuid (NOT a name) — get it from search\_entities (e.g. "ERBB4" → "ENSG00000178568")
* `topN` — max number of rankings to surface (optional; default 20, capped at 50) — the op pre-sorts best-rank-first, so this keeps the strongest standings; `count` still reports the full total
* `includeArchived` — include archived (historical) reports in the rankings (optional; default false) — by default only current reports are returned, so rankings\[0] is the entity's current best standing

**Returns:** An object { objectId, count, rankings }. count is the DENOMINATOR — how many reports the entity is ranked in across all models (the FULL total of the matching reports, before any topN cap); rankings returns the best `topN` of those, so if count > rankings.length you are seeing the top slice — raise topN to see more (there is no truncated flag). rankings is best-rank-first; each has: modelId + modelName, reportId + reportName (modelId/reportId are the handles to drill in next — reportId into get\_evidence / get\_report\_scores, modelId into search\_models), anchorConcept (what the report is anchored on, e.g. Disease — { dbLabel, displayName }), rank + total (its position out of N), score (raw weighted sum) and normScore (0–1 within the report) — keep both. archived is flagged per ranking; archived (historical) reports are excluded unless includeArchived is true. Use rankings\[0] for the entity's single best standing and quote its modelName + rank.

## Parameters

| Parameter         | Type    | Required | Description                                                                                                                                                                            |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `objectId`        | string  | yes      | the entity's graph-node uuid (NOT a name) — get it from search\_entities (e.g. "ERBB4" → "ENSG00000178568")                                                                            |
| `topN`            | number  | no       | max number of rankings to surface (optional; default 20, capped at 50) — the op pre-sorts best-rank-first, so this keeps the strongest standings; `count` still reports the full total |
| `includeArchived` | boolean | no       | include archived (historical) reports in the rankings (optional; default false) — by default only current reports are returned, so rankings\[0] is the entity's current best standing  |

## Response

```ts
{
  objectId: string;
  count: number;
  rankings: Array<{
    modelId: string | null;
    modelName: string | null;
    reportId: string | null;
    reportName: string | null;
    anchorConcept: {
      dbLabel: string | null;
      displayName: string | null;
    } | null;
    archived: boolean;
    rank: number;
    total: number;
    score: number | null;
    normScore: number | null;
  }>;
}
```

## Example

```json
// where_entity_ranks({"objectId":"ENSG00000178568"})
{
  "objectId": "ENSG00000178568"
}
```

Response (arrays truncated):

```json
{
  "objectId": "ENSG00000178568",
  "count": 13,
  "rankings": [
    {
      "modelId": "7oNxw84sOcCi0v8h2fn15",
      "modelName": "Neurodegenerative Target Prioritization 2",
      "reportId": "mbYRHvcGOSp4Wsl",
      "reportName": "ALS",
      "anchorConcept": {
        "dbLabel": "Disease",
        "displayName": "Disease"
      },
      "archived": false,
      "rank": 1,
      "total": 44750,
      "score": 1.1987416527906658,
      "normScore": 0.3878177499422183
    },
    {
      "modelId": "Ok8nsoMnRLWiC_YByOslb",
      "modelName": "Neurodegenerative Target Prioritization + Pathways",
      "reportId": "CR-Ksa7pFW1SOnDyPQ0kd",
      "reportName": "ALS",
      "anchorConcept": {
        "dbLabel": "Disease",
        "displayName": "Disease"
      },
      "archived": false,
      "rank": 1,
      "total": 44750,
      "score": 1.3274501206893674,
      "normScore": 0.36858877328971584
    },
    {
      "modelId": "d3wyAtDLSewvY90zVcrAP",
      "modelName": "Neurodegenerative Target Prioritization 3",
      "reportId": "3EIVH6mRrz3lQLu",
      "reportName": "ALS",
      "anchorConcept": {
        "dbLabel": "Disease",
        "displayName": "Disease"
      },
      "archived": false,
      "rank": 1,
      "total": 39542,
      "score": 1.5162798625413438,
      "normScore": 0.2552555043353279
    },
    "… 10 more"
  ]
}
```