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

# Get Polymarket Orderbook Summary

> Retrieve a bucketed best bid/best ask time series for a Polymarket market condition on a UTC date or custom timestamp window.

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer YOUR_API_KEY`
</ParamField>

### Query Parameters

<ParamField query="condition_id" type="string" required>
  The Polymarket market condition ID. Values are accepted with or without the `0x` prefix.
</ParamField>

<ParamField query="asset_id" type="string" required>
  CLOB token ID to summarize within the condition. Polymarket conditions can have multiple outcome token books, so this parameter is required.
</ParamField>

<Tip>
  To find `asset_id` values, request a small page from [Get Polymarket Market Data](/api-reference/endpoint/get-market-data) and collect the unique `asset_id` fields. See [Examples](/examples#find-polymarket-asset-ids).
</Tip>

<ParamField query="date" type="string">
  The UTC date to summarize, formatted as `YYYY-MM-DD`. Required unless `start_timestamp` and `end_timestamp` are provided.
</ParamField>

<ParamField query="start_timestamp" type="integer">
  Inclusive lower timestamp bound in Unix seconds or milliseconds. Must be provided with `end_timestamp`.
</ParamField>

<ParamField query="end_timestamp" type="integer">
  Inclusive upper timestamp bound in Unix seconds or milliseconds. Must be provided with `start_timestamp`.
</ParamField>

<ParamField query="resolution" type="integer">
  Time bucket resolution in seconds. Default: `60`. Valid range: `1` to `3600`.
</ParamField>

<Note>
  Use `date` for a full UTC day, or use `start_timestamp` and `end_timestamp` for a custom UTC window. Custom windows hydrate book state from earlier records in the loaded UTC date partitions and emit buckets inside the requested range.
</Note>

## Response

<ResponseField name="market_condition_id" type="string">
  The Polymarket market condition ID.
</ResponseField>

<ResponseField name="asset_id" type="string">
  The CLOB token ID used for the summary.
</ResponseField>

<ResponseField name="date" type="string">
  The requested date.
</ResponseField>

<ResponseField name="resolution_seconds" type="integer">
  The bucket size used to build the summary.
</ResponseField>

<ResponseField name="data_points" type="integer">
  Number of summary points returned.
</ResponseField>

<ResponseField name="data" type="array">
  Array of time buckets. Each bucket includes close values and OHLC candles:

  <Expandable title="Bucket fields">
    <ResponseField name="timestamp" type="integer">
      Bucket start timestamp in Unix milliseconds.
    </ResponseField>

    <ResponseField name="quote_count" type="integer">
      Number of reconstructed top-of-book observations in this bucket. Forward-filled buckets use `0`.
    </ResponseField>

    <ResponseField name="is_forward_filled" type="boolean">
      `true` when no quote was observed in this bucket and values were carried forward from the previous bucket.
    </ResponseField>

    <ResponseField name="best_bid" type="number">
      Close value for the best bid in this bucket.
    </ResponseField>

    <ResponseField name="best_bid_size" type="number">
      Close size for the best bid in this bucket.
    </ResponseField>

    <ResponseField name="best_ask" type="number">
      Close value for the best ask in this bucket.
    </ResponseField>

    <ResponseField name="best_ask_size" type="number">
      Close size for the best ask in this bucket.
    </ResponseField>

    <ResponseField name="mid_price" type="number">
      Close midpoint, computed as `(best_bid + best_ask) / 2` when both sides are present.
    </ResponseField>

    <ResponseField name="spread" type="number">
      Close spread, computed as `best_ask - best_bid` when both sides are present.
    </ResponseField>

    <ResponseField name="best_bid_ohlc" type="object">
      OHLC values for every best-bid quote observed inside the bucket.
    </ResponseField>

    <ResponseField name="best_ask_ohlc" type="object">
      OHLC values for every best-ask quote observed inside the bucket.
    </ResponseField>

    <ResponseField name="mid_price_ohlc" type="object">
      OHLC values for every midpoint observed inside the bucket.
    </ResponseField>

    <ResponseField name="spread_ohlc" type="object">
      OHLC values for every spread observed inside the bucket.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The legacy alias `GET /api/v1/market/orderbook-summary` remains available for existing integrations.
</Note>

## Example

<CodeGroup>
  ```python Python SDK theme={null}
  from entityml import EntityMLClient

  client = EntityMLClient(api_key="YOUR_API_KEY")

  summary = client.polymarket.get_orderbook_summary(
      condition_id="0x8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4",
      asset_id="97684905927345553455494278582909124912046930226695064344571162061840768197777",
      start_timestamp=1770940800000,
      end_timestamp=1770944399999,
      resolution=60,
  )

  print(summary["data_points"])
  ```

  ```bash CLI theme={null}
  export ENTITY_API_KEY="YOUR_API_KEY"

  entityml polymarket orderbook-summary \
    --condition-id 0x8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4 \
    --asset-id 97684905927345553455494278582909124912046930226695064344571162061840768197777 \
    --start-timestamp 1770940800000 \
    --end-timestamp 1770944399999 \
    --resolution 60
  ```

  ```bash Raw HTTP (cURL) theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.entityml.com/api/v1/polymarket/market/orderbook-summary?condition_id=8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4&asset_id=97684905927345553455494278582909124912046930226695064344571162061840768197777&start_timestamp=1770940800000&end_timestamp=1770944399999&resolution=60"
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://api.entityml.com/api/v1/polymarket/market/orderbook-summary",
      headers={"Authorization": f"Bearer {os.environ['ENTITY_API_KEY']}"},
      params={
          "condition_id": "0x8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4",
          "asset_id": "97684905927345553455494278582909124912046930226695064344571162061840768197777",
          "start_timestamp": 1770940800000,
          "end_timestamp": 1770944399999,
          "resolution": 60,
      },
      timeout=30,
  )
  response.raise_for_status()
  summary = response.json()
  print(summary["data_points"])
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    condition_id: "0x8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4",
    asset_id: "97684905927345553455494278582909124912046930226695064344571162061840768197777",
    start_timestamp: "1770940800000",
    end_timestamp: "1770944399999",
    resolution: "60"
  });

  const response = await fetch(
    `https://api.entityml.com/api/v1/polymarket/market/orderbook-summary?${params}`,
    { headers: { Authorization: `Bearer ${process.env.ENTITY_API_KEY}` } }
  );

  const summary = await response.json();
  console.log(summary.data_points);
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "market_condition_id": "0x8213d395e079614d6c4d7f4cbb9be9337ab51648a21cc2a334ae8f1966d164b4",
  "asset_id": "97684905927345553455494278582909124912046930226695064344571162061840768197777",
  "date": null,
  "start_timestamp": 1770940800000,
  "end_timestamp": 1770944399999,
  "resolution_seconds": 60,
  "data_points": 1440,
  "data": [
    {
      "timestamp": 1770940800000,
      "quote_count": 42,
      "is_forward_filled": false,
      "best_bid": 0.12,
      "best_bid_size": 4361.9,
      "best_ask": 0.15,
      "best_ask_size": 4361.9,
      "mid_price": 0.135,
      "spread": 0.03,
      "best_bid_ohlc": { "open": 0.11, "high": 0.12, "low": 0.1, "close": 0.12 },
      "best_ask_ohlc": { "open": 0.16, "high": 0.16, "low": 0.15, "close": 0.15 },
      "mid_price_ohlc": { "open": 0.135, "high": 0.14, "low": 0.125, "close": 0.135 },
      "spread_ohlc": { "open": 0.05, "high": 0.06, "low": 0.03, "close": 0.03 }
    }
  ]
}
```