---
title: "Polymarket Volume History"
method: GET
path: "/gateway/v1/prediction-market/polymarket/volumes"
tags: ["Prediction Market"]
---

# Polymarket Volume History

`GET /gateway/v1/prediction-market/polymarket/volumes`

## Request

- Base URL: `https://api.asksurf.ai`
- URL: `https://api.asksurf.ai/gateway/v1/prediction-market/polymarket/volumes`
- Auth: HTTP bearer

Aggregate trading volume (USD) and trade count as a time series.
Use this for volume trend analysis.
For YES/NO volume breakdown by outcome side, use `volume-split` instead.

**Data refresh:** ~30 minutes

## Query parameters

- `condition_id` string: Market condition identifier (required if token_id not provided)
- `token_id` string: Token ID (alternative identifier, resolved to condition_id internally)
- `time_range` '7d' | '30d' | '90d' | '180d' | '1y': Window of history to return (how much data, from now backward): `7d`, `30d`, `90d`, `180d`, or `1y`. Distinct from `interval` (which sets bucket size within the window).
- `interval` '1h' | '1d': Bucket size for each point in the returned series: `1h` (hourly) or `1d` (daily). Distinct from `time_range` (which sets the window size).
- `granularity` 'day' | 'week' | 'month' | 'year' | 'all': Aggregation granularity (alternative to interval). When provided, queries daily table with buy/sell volume breakdown.
- `start_time` integer: Start time as Unix seconds (alternative to time_range)
- `end_time` integer: End time as Unix seconds (alternative to time_range)

## Response `200`

OK

- DataResponsePolymarketVolumePoint
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `data` PolymarketVolumePoint[], nullable, required
    - `buy_volume` number, double: Buy-side volume (USD), available when using granularity param
    - `notional_volume_usd` number, double, required: Notional trading volume in USD
    - `sell_volume` number, double: Sell-side volume (USD), available when using granularity param
    - `timestamp` integer, required: Interval start Unix timestamp in seconds
    - `trade_count` integer, required: Number of trades
  - `meta` OffsetMeta, required
    - `cached` boolean, required: Whether this response was served from cache
    - `credits_used` integer, required: Credits deducted for this request
    - `empty_reason` string: Hint explaining why the data array is empty, when applicable
    - `has_more` boolean: Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required: Maximum number of items returned in this response
    - `offset` integer, required: Number of items skipped (pagination offset)
    - `total` integer: Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer: Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) - [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/revisions/91774fdd5302?raw)