---
title: "Get a market ranking at every bucket of a window"
url: https://docs.truemarkets.co/api/market-data/get-scan-history
description: "Returns the ranking a scanner or a universe rotation is built on, taken at every bucket across a lookback window rather than only at now."
---

Docs index: https://docs.truemarkets.co/llms.txt

# Get a market ranking at every bucket of a window

Returns the ranking a scanner or a universe rotation is built on, taken
at every bucket across a lookback window rather than only at now.

Every span a ranking measures is read backwards from its own bucket, so
no bucket reflects a figure the market had not reported yet. Ranking a
month of hourly buckets over the whole tracked universe would be
hundreds of thousands of rows, so each bucket carries only its top
`per_bucket` assets, ordered best first on the requested `source`.
Assets without a symbol or without a spot price source are dropped, the
same way the live feeds drop them.

`value` is the figure the source ranks on: a trending ratio, a recent
volume in USD, or a signed price change percentage. Ranking is on that
signed figure, so `sort=desc` on a `surging_*` source is the gainers and
`sort=asc` is the fallers.

See the [Time Window & Resolution](https://docs.truemarkets.co/api/market-data/market-data-service-api#time-window--resolution)
section for the format of `window` and `resolution`.

## Request

```
GET https://api.truemarkets.co/v1/defi/market/market-data/scans/history
```

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `source` | query | string, one of `trending_ratio`, `volume`, `surging_1h`, `surging_4h`, `surging_24h` | yes | Which ranking to take. |
| `sort` | query | string, one of `desc`, `asc` | no | Which end of the ranking each bucket keeps. Buckets are capped before they are served, so this must match the sort the caller will rank by: a "biggest dippers" scanner asking for `desc` would be handed the gainers it was never going to buy. |
| `window` | query | string | no | Lookback period (e.g. `1h`, `4h`, `1d`, `7d`, `1M`). |
| `resolution` | query | string | no | Bucket size (e.g. `5m`, `1h`, `1d`). Must be at least `1h` for windows over `1d`. |
| `per_bucket` | query | integer | no | How many assets each bucket carries, capped at 200. |

## Responses

Every error status returns the same body, described in [Errors](https://docs.truemarkets.co/developer-resources/errors.md).

### 200

The ranking at each bucket of the window

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | no | The ranking that was taken |
| `sort` | string | no | Which end of the ranking each bucket kept |
| `window` | string | no | The time window used for the query |
| `resolution` | string | no | The time resolution used for the query |
| `per_bucket` | integer | no | The most assets any bucket carries |
| `buckets` | array of object | no | One ranking per bucket, oldest first |
| `buckets[].t` | string (date-time) | no | ISO 8601 timestamp of the bucket |
| `buckets[].assets` | array of object | no | The bucket's top assets, best first |
| `buckets[].assets[].asset_id` | string (uuid) | no | Backend asset ID |
| `buckets[].assets[].symbol` | string | no | The asset symbol |
| `buckets[].assets[].value` | string | no | The figure the source ranks on, signed for a price change |

### 400

Bad request - unknown source or invalid parameters

### 404

No ranking data in the window

### 500

Internal server error
