> 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/get-report-scores.md).

# get\_report\_scores — Get report scores

Get report scores

Get report scores

## What it does

Return the ranked, scored rows of a scoring report — counts-first and paginated: the report's total hit count plus a capped page of top-scoring entities (genes / targets / pathways).

**When to use:** the user asks "what are the top targets / genes / pathways for X?" and you already have the report's reportId (from list\_reports); you want a specific entity's score and rank in a report — pass `displayName` (returns just that row, totalHits 1, no paging); paging deeper into a large report (pass `offset`) — ranks continue across pages.

**When NOT to use:** you don't have a reportId yet (find one with list\_reports / search\_models first); the user asks about the model's CONFIG or scoring criteria (use get\_reasoning\_model); the user asks WHY a gene scores the way it does — its evidence (use get\_evidence); the user wants a gene's rank ACROSS models, not within one report (use where\_entity\_ranks).

**Parameters:**

* `reportId` — the scoring report's id (from list\_reports) — which report's rows to read
* `limit` — max rows to return on this page (optional; default 10, capped at 100) — NOT the total
* `offset` — 0-based row offset for paging deeper into a large report (optional; default 0)
* `displayName` — an entity's display name (e.g. "ERBB4") — returns ONLY that entity's row (totalHits 1), the way to get one entity's score/rank without paging the whole report

**Returns:** An object { reportId, reportName, anchorConcept, snapshot, totalHits, hasMore, offset, returnedCount, rows }. anchorConcept is the concept the report is anchored on (e.g. Disease — { dbLabel, displayName }). totalHits is the FULL row count of the report (can be tens of thousands — this is counts-first, the rows array is just one page); hasMore is true if rows remain beyond this page; offset is this page's start and returnedCount is how many rows came back (≤ limit). Each row has: rank (1-based, within the report), displayName, dbLabels (graph labels), score (raw weighted sum — quote this for "top target"), and normScore (0–1 within the report — quote this for "percentile"), plus uuid (the handle for evidence drill-down). snapshot (the report's last-updated timestamp) + reportId are provenance — cite them so every number is traceable. CAVEAT: scores can tie (e.g. many drugs at one score); on equal scores assert set-membership, not a strict #1. When the reportId resolves to no report, the tool returns a 404 Not Found error (isError).

## Parameters

| Parameter     | Type   | Required | Description                                                                                                                                                    |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reportId`    | string | yes      | the scoring report's id (from list\_reports) — which report's rows to read                                                                                     |
| `limit`       | number | no       | max rows to return on this page (optional; default 10, capped at 100) — NOT the total                                                                          |
| `offset`      | number | no       | 0-based row offset for paging deeper into a large report (optional; default 0)                                                                                 |
| `displayName` | string | no       | an entity's display name (e.g. "ERBB4") — returns ONLY that entity's row (totalHits 1), the way to get one entity's score/rank without paging the whole report |

## Response

```ts
{
  reportId: string;
  reportName: string | null;
  anchorConcept: {
    dbLabel: string | null;
    displayName: string | null;
  } | null;
  snapshot: string | null;
  totalHits: number;
  hasMore: boolean;
  offset: number;
  returnedCount: number;
  rows: Array<{
    rank: number;
    uuid: string | null;
    displayName: string | null;
    dbLabels: string[];
    score: number | null;
    normScore: number | null;
  }>;
}
```

## Example

```json
// get_report_scores({"reportId":"HSMbRGwjjagowaeYsjH36"})
{
  "reportId": "HSMbRGwjjagowaeYsjH36"
}
```

Response (arrays truncated):

```json
{
  "reportId": "HSMbRGwjjagowaeYsjH36",
  "reportName": "Psoriasis",
  "anchorConcept": {
    "dbLabel": "Disease",
    "displayName": "Disease"
  },
  "snapshot": "2026-06-26T19:40:44.911Z",
  "totalHits": 11881,
  "hasMore": true,
  "offset": 0,
  "returnedCount": 10,
  "rows": [
    {
      "rank": 1,
      "uuid": "ENSG00000143556",
      "displayName": "S100A7",
      "dbLabels": [
        "Gene",
        "ProteinCoding"
      ],
      "score": 1.7807447042554605,
      "normScore": 0.7352979594317693
    },
    {
      "rank": 2,
      "uuid": "ENSG00000105397",
      "displayName": "TYK2",
      "dbLabels": [
        "Gene",
        "ProteinCoding"
      ],
      "score": 1.579697680681583,
      "normScore": 0.6522824290020376
    },
    {
      "rank": 3,
      "uuid": "ENSG00000096968",
      "displayName": "JAK2",
      "dbLabels": [
        "Gene",
        "ProteinCoding"
      ],
      "score": 1.5290068148982228,
      "normScore": 0.6313513600603397
    },
    "… 7 more"
  ]
}
```