# Raw order book snapshot

### What is this endpoint for? 

The raw data on which our Level 2 Aggregations such as market depth , bid/ask spread, and price slippage are built. Details a point-in-time view of the bids and asks on an exchange's order book to 10% depth. Used to build your own custom level 2 aggregations. 

### Endpoint

{% code overflow="wrap" %}

```url
https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/{exchange}/{instrument_class}/{instrument}/snapshots/raw
```

{% endcode %}

### Path Parameters

<table><thead><tr><th width="203">Parameter</th><th>Required?</th><th>Description</th></tr></thead><tbody><tr><td><code>region</code></td><td>Yes</td><td>Choose between <code>eu</code> and <code>us</code>.</td></tr><tr><td><code>exchange</code></td><td>Yes</td><td><p>Exchange <code>code.</code> </p><p><br>See <a data-mention href="/pages/QiW5iUvcyBF9RISFmZFV">/pages/QiW5iUvcyBF9RISFmZFV</a></p></td></tr><tr><td><code>instrument_class</code></td><td>Yes</td><td>Instrument <code>class</code>. <br><br>See <a data-mention href="/pages/8ywkQXfxfv1FjtyspEaU">/pages/8ywkQXfxfv1FjtyspEaU</a></td></tr><tr><td><code>instrument</code></td><td>Yes</td><td>Instrument <code>code</code>.<br><br>See <a data-mention href="/pages/8ywkQXfxfv1FjtyspEaU">/pages/8ywkQXfxfv1FjtyspEaU</a></td></tr></tbody></table>

### Query Parameters

<table><thead><tr><th width="220">Parameter</th><th width="129">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>continuation_token</code></td><td>No</td><td>See <a data-mention href="/pages/mP3amLsYqKTsrRBoblxX">/pages/mP3amLsYqKTsrRBoblxX</a></td></tr><tr><td><code>limit_orders</code></td><td>No</td><td>Number of orders to return on bid and ask side per snapshot.<br><br>To retreive the best bid/ask, set this parameter to <code>1</code> <br><br>Default: <code>10</code></td></tr><tr><td><code>page_size</code></td><td>No</td><td>Number of snapshots to return data for. <br><br>Default: <code>10</code><br>Max: <code>100</code><br><br>See <a data-mention href="/pages/mP3amLsYqKTsrRBoblxX">/pages/mP3amLsYqKTsrRBoblxX</a><br> <br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>sort</code></td><td>No</td><td>Return the data in ascending (asc) or descending (desc) order. <br><br>Default: <code>desc</code><br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>start_time</code></td><td>No</td><td>Starting time in ISO 8601 (inclusive).<br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>end_time</code></td><td>No</td><td>Ending time in ISO 8601 (exclusive).<br><br><em>Automatically included in continuation tokens.</em></td></tr></tbody></table>

### Fields

<table><thead><tr><th width="294">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>poll_timestamp</code></td><td>The timestamp at which the raw data snapshot was taken.</td></tr><tr><td><code>poll_date</code></td><td>The date at which the raw data snapshot was taken.</td></tr><tr><td><code>timestamp</code></td><td>The timestamp provided by the exchange. <code>null</code> when not provided.</td></tr><tr><td><code>asks</code></td><td>The sell orders in the snapshot. If the <code>limit_oders</code> parameter is used, this will be reflected here. <code>amount</code> is the quantity of asset to sell, displayed in the base currency. <code>price</code> is displayed in the quote currency.</td></tr><tr><td><code>bids</code></td><td>The buy orders in the snapshot. If the <code>limit_oders</code> parameter is used, this will be reflected here. <code>amount</code> is the quantity of asset to buy, displayed in the base currency. <code>price</code> is displayed in the quote currency.</td></tr></tbody></table>

### Request examples

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```url
curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/snapshots/raw?page_size=10&limit_orders=2'
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

```python
##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
exchange = "krkn" 
instrument_class = "spot"
pair = "btc-usd" #called "instrument" in the documentation

# ---- Optional parameters ---- #
sort = "desc"
page_size = 100
start_time= "2025-03-03T00:00:00Z"
end_time= "2025-03-05T00:00:00Z"
limit_orders = 10

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, exchange: str, pair: str, instrument_class: str, start_time: str, end_time: str, sort: str, page_size: int, limit_orders: int):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/{exchange}/{instrument_class}/{pair}/snapshots/raw'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size,
        "limit_orders": limit_orders
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, exchange=exchange, pair=pair, instrument_class=instrument_class, start_time=start_time, end_time=end_time ,sort=sort, page_size=int(page_size), limit_orders=limit_orders)
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response example

```json
{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 0,
        "limit_orders": 2,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "metric": "raw",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:13:08.823Z"
    },
    "time": "2020-05-26T14:13:08.899Z",
    "timestamp": 1590502388899,
    "data": [
        {
            "poll_timestamp": 1590502335760,
            "poll_date": "2020-05-26T14:12:15.760Z",
            "timestamp": null,
            "asks": [
                {
                    "amount": "12",
                    "price": "8830"
                },
                {
                    "amount": "3.67",
                    "price": "8832.9"
                }
            ],
            "bids": [
                {
                    "amount": "13.316",
                    "price": "8829.9"
                },
                {
                    "amount": "0.097",
                    "price": "8829.4"
                }
            ]
        }
      /* ... */         
    ],
    "result": "success",
    "continuation_token": "Z8FjTagUoHd3UCqMvqmRJXlwzbTxSnSXpxxZpHWNCmrsrcnhSpMG2gdcmFKRPd88",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/cbse/spot/btc-usd/snapshots/raw?continuation_token=Z8FjTagUoHd3UCqMvqmRJXlwzbTxSnSXpxxZpHWNCmrsrcnhSpMG2gdcmFKRPd88",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kaiko.com/rest-api/data-feeds/level-1-and-level-2-data/level-2-aggregations/raw-order-book-snapshot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.