> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bravadotrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /perps/liquidations: Liquidation History

> Detected Polymarket Perps liquidations, oldest first, each carrying its evidence class. Indeterminate fields are null, never a fabricated zero. Scope analytics.read.

> [!NOTE]
>
> Sign each request with a fresh HMAC signature. The cURL and HTTP header values below are placeholders, not reusable credentials. For runnable signing code, use [request signing examples](https://docs.bravadotrade.com/authentication-examples.md).

Detected liquidations, **oldest first**. Every row carries its `evidence` class — `confirmed`, `inferred` or `unknown` — so you can tell a liquidation observed directly from one reconstructed from account state. Fields that cannot be determined are `null`, never `0` or `false`. Detection covers the **gated account-snapshot universe only**. Part of the [Perps Data](https://docs.bravadotrade.com/products/perps-data.md) product; scope `analytics.read`.

```text theme={null}
GET https://partner-api.bravadotrade.com/perps/liquidations
```

### Query Parameters

**from** `string` *required*

Start of the window. Accepts RFC3339, unix seconds or unix milliseconds.

**to** `string` *required*

End of the window. Same formats as `from`. The window may span at most **31 days**; a wider range is refused with `400 range_too_large`.

**instrument** `string`

Only liquidations on this instrument, by its venue-native id. Matches `[A-Za-z0-9._-]{1,32}`. Omit for all instruments.

**address** `string`

Only liquidations for this account. A 40-hex address, with or without the `0x` prefix.

**evidence** `string`

A comma-separated subset of `confirmed`, `inferred`, `unknown`. Defaults to all three. `unknown` is never hidden, so a subset that omits it still returns `unknown` rows. An unrecognised value is refused with `400 invalid_evidence`.

**limit** `integer` (default: 200)

Rows per page, `1`–`1000`.

### Response

Liquidations in `data`, oldest first, each with its evidence class. When `has_more` is `true`, page forward by passing `next_from_ms` back as `from`.

**data** `array`

**Liquidation fields**

**liq\_id** `string`

Stable id for the detected liquidation.

**detected\_ts\_ms** `integer`

When the liquidation was detected, in unix milliseconds (`detected_ts` in seconds).

**instrument** `string`

The instrument liquidated, by its venue-native id.

**venue** `string`

The venue.

**address** `string`

The liquidated account.

**evidence** `string`

How the liquidation was established: `confirmed` (observed directly), `inferred` (reconstructed from account state), or `unknown`.

**position\_side** `string | null`

The side liquidated, or `null` when it cannot be determined — never a guessed value.

**closed\_size** `string | null`

Size closed by the liquidation, or `null` when indeterminate — never `0`. Related sizing fields (`fill_size`, `size_before`, `size_after`) follow the same null-not-zero rule, as do the price and equity fields (`entry_price`, `fill_price`, `mark_before`, `mark_extreme`, `equity_before_usd`, `equity_after_usd`, `equity_drop_usd`, `liq_price_est`, `notional_usd`) and the fee fields (`liq_fee_bps`, `expected_liq_fee_usd`, `fill_fee_usd`).

**adl** `boolean | null`

Whether the liquidation was an auto-deleverage, or `null` when indeterminate.

**change\_kind** `string`

The kind of position change observed (`fills_source` records where the fills came from; `rule_version` the detection rule).

**completeness** `object`

What the detection could and could not observe over the window.

**has\_more** `boolean`

`true` when more rows remain beyond this page.

**next\_from\_ms** `integer`

Present when `has_more` is `true`. Pass it back as `from` to read the next page.

### Example

```bash cURL theme={null}
curl -G https://partner-api.bravadotrade.com/perps/liquidations \
  -H "X-BRAVADO-API-KEY: $BRAVADO_API_KEY" \
  -H "X-BRAVADO-TIMESTAMP: <unix-ms>" \
  -H "X-BRAVADO-SIGNATURE: <signature-for-this-request>" \
  -d from=2026-10-01T00:00:00Z \
  -d to=2026-10-02T00:00:00Z \
  -d evidence=confirmed,inferred
```

```json Response (abbreviated) theme={null}
{
  "data": [
    {
      "liq_id": "6:0xef3990a7:1759276920000",
      "detected_ts_ms": 1759276920000,
      "instrument": "6",
      "venue": "polymarket",
      "address": "0xef3990a7c8fa92d84dce0e7816ca3410820c1d36",
      "evidence": "confirmed",
      "position_side": "long",
      "closed_size": "12.50",
      "notional_usd": "1125375.00",
      "adl": false,
      "change_kind": "liquidation"
    },
    {
      "liq_id": "6:0x7c80413d:1759277500000",
      "detected_ts_ms": 1759277500000,
      "instrument": "6",
      "venue": "polymarket",
      "address": "0x7c80413d2b9a1f5e6d3c4b2a1908f7e6d5c4b3a2",
      "evidence": "inferred",
      "position_side": null,
      "closed_size": null,
      "notional_usd": null,
      "adl": null,
      "change_kind": "liquidation"
    }
  ],
  "completeness": { "observed_universe_only": true },
  "has_more": true,
  "next_from_ms": 1759363200000
}
```

## Related

* [Long/short skew](https://docs.bravadotrade.com/api/perps-data/skew.md) — positioning over the same observed account universe.
* [Perps Data overview](https://docs.bravadotrade.com/products/perps-data.md) — the product, its credential and shared conventions.


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