---
updatedAt: 2026-08-25T15:23:33.000Z
agentTools:
  projectIndex: https://docs.tatum.io/llms.txt
---

# Get market price history

<p style='display: none'>/v4/data/prediction/markets/{id}/history</p>
<p><b>200 credits per API call</b></p>

<p>Historical OHLC price candles for a market over a time window. Used to power
chart views — every candle includes open / high / low / close prices plus the
in-bucket trade volume.</p>

<p><b>Filtering</b></p>
<ul>
<li><code>interval</code> is required. Accepted values: <code>1m</code>,
<code>5m</code>, <code>15m</code>, <code>1h</code>, <code>4h</code>,
<code>1d</code>, <code>1w</code>. Each interval has a maximum allowed range
(e.g. <code>1m</code> can be queried for ~1 day at a time, <code>1d</code> for
~1 year). Requests exceeding the range cap return <code>400</code>.</li>
<li><code>start</code> and <code>end</code> are required ISO-8601 timestamps.
<code>end</code> must be after <code>start</code>.</li>
<li><code>source</code> selects the underlying data feed. Defaults to
<code>candlesticks</code> (trade-based OHLC with real volume). Pass
<code>midpoint</code> to switch to a midpoint-quote feed with broader range
coverage at the cost of <code>volume = 0</code> on every candle.
<code>source=midpoint</code> is supported on Polymarket only — passing it
against a Kalshi market returns <code>400</code>.</li>
</ul>

<p><b>Other notes</b></p>
<ul>
<li><code>partial: true</code> indicates the requested range was truncated by an
upstream availability limit. This only happens on Polymarket with
<code>source=candlesticks</code> (the trade-based feed exposes a finite window
of historical fills); Kalshi candles cover the full requested range, and
<code>source=midpoint</code> on Polymarket also covers the full range.</li>
<li>When <code>partial</code> is <code>true</code>, <code>availableFrom</code>
contains the earliest timestamp the response actually covers — data before that
point is unavailable from the trade-based feed. To recover the missing range on
Polymarket, repeat the call with <code>source=midpoint</code>; the response
spans the full window at the cost of <code>volume = 0</code> on every candle
(the midpoint feed carries quotes, not fills).</li>
<li><code>availableFrom</code> is <code>null</code> when no trades exist in the
entire requested range.</li>
<li>Candle timestamps are bucket-aligned (e.g. an <code>interval=1h</code>
response has timestamps on the hour).</li>
</ul>


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "servers": [
    {
      "url": "https://api.tatum.io"
    }
  ],
  "info": {
    "version": "1.2",
    "title": "Blockchain Data"
  },
  "tags": [
    {
      "name": "Prediction API"
    }
  ],
  "paths": {
    "/v4/data/prediction/markets/{id}/history": {
      "get": {
        "description": "<p style='display: none'>/v4/data/prediction/markets/{id}/history</p>\n<p><b>200 credits per API call</b></p>\n\n<p>Historical OHLC price candles for a market over a time window. Used to power\nchart views — every candle includes open / high / low / close prices plus the\nin-bucket trade volume.</p>\n\n<p><b>Filtering</b></p>\n<ul>\n<li><code>interval</code> is required. Accepted values: <code>1m</code>,\n<code>5m</code>, <code>15m</code>, <code>1h</code>, <code>4h</code>,\n<code>1d</code>, <code>1w</code>. Each interval has a maximum allowed range\n(e.g. <code>1m</code> can be queried for ~1 day at a time, <code>1d</code> for\n~1 year). Requests exceeding the range cap return <code>400</code>.</li>\n<li><code>start</code> and <code>end</code> are required ISO-8601 timestamps.\n<code>end</code> must be after <code>start</code>.</li>\n<li><code>source</code> selects the underlying data feed. Defaults to\n<code>candlesticks</code> (trade-based OHLC with real volume). Pass\n<code>midpoint</code> to switch to a midpoint-quote feed with broader range\ncoverage at the cost of <code>volume = 0</code> on every candle.\n<code>source=midpoint</code> is supported on Polymarket only — passing it\nagainst a Kalshi market returns <code>400</code>.</li>\n</ul>\n\n<p><b>Other notes</b></p>\n<ul>\n<li><code>partial: true</code> indicates the requested range was truncated by an\nupstream availability limit. This only happens on Polymarket with\n<code>source=candlesticks</code> (the trade-based feed exposes a finite window\nof historical fills); Kalshi candles cover the full requested range, and\n<code>source=midpoint</code> on Polymarket also covers the full range.</li>\n<li>When <code>partial</code> is <code>true</code>, <code>availableFrom</code>\ncontains the earliest timestamp the response actually covers — data before that\npoint is unavailable from the trade-based feed. To recover the missing range on\nPolymarket, repeat the call with <code>source=midpoint</code>; the response\nspans the full window at the cost of <code>volume = 0</code> on every candle\n(the midpoint feed carries quotes, not fills).</li>\n<li><code>availableFrom</code> is <code>null</code> when no trades exist in the\nentire requested range.</li>\n<li>Candle timestamps are bucket-aligned (e.g. an <code>interval=1h</code>\nresponse has timestamps on the hour).</li>\n</ul>\n",
        "operationId": "GetPredictionMarketPriceHistory",
        "parameters": [
          {
            "description": "Platform-native market identifier.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917"
            }
          },
          {
            "description": "Candle bucket size.",
            "in": "query",
            "name": "interval",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/PredictionHistoryInterval"
            }
          },
          {
            "description": "Window start (ISO-8601). Must be earlier than `end`.",
            "in": "query",
            "name": "start",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-05-01T00:00:00Z"
            }
          },
          {
            "description": "Window end (ISO-8601). Must be later than `start`.",
            "in": "query",
            "name": "end",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-05-15T00:00:00Z"
            }
          },
          {
            "description": "Data source. Defaults to `candlesticks`. `midpoint` is Polymarket-only.\n",
            "in": "query",
            "name": "source",
            "schema": {
              "$ref": "#/components/schemas/PredictionHistorySource"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PredictionPriceHistoryResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "description": "Market not found on any supported platform."
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        },
        "security": [
          {
            "X-API-Key": []
          }
        ],
        "x-codeSamples": [],
        "summary": "Get market price history",
        "tags": [
          "Prediction API"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "X-API-Key": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header",
        "description": "Your **API key** is used to identify your account & your plan, including the number of API calls per second and total monthly calls you have.\n\nEach key is for individual use only.\n\nIf you don't have a key already you can [Sign up for a Free Tatum account](https://co.tatum.io/signup) to get two keys (testnet and mainnet), allowing up to 5 API calls per second and 1,000,000 Credits.\n\nFor testing purposes, you can use the following key which only works inside docs and has limited functionality (e.g. you cannot create virtual accounts or notification subscriptions with it):\n* t-66a730ccccfd17001c479705-2f597d14ad7543f289a03418\n\nFor more details on limits and plans, [click here](https://docs.tatum.io/docs/plans-limits).\n"
      }
    },
    "responses": {
      "Error400": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "errorCode": {
                  "example": "validation.failed",
                  "description": "validation.failed",
                  "type": "string"
                },
                "message": {
                  "example": "Request validation failed. Please see data for additional information.",
                  "description": "Request validation failed. Please see data for additional information.",
                  "type": "string"
                },
                "statusCode": {
                  "example": 400,
                  "description": "400",
                  "type": "number"
                },
                "data": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "target"
                    ],
                    "properties": {
                      "target": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Request object present in the body of the HTTP request",
                        "example": {
                          "property": 12345
                        }
                      },
                      "value": {
                        "type": "number",
                        "description": "Value of the target object which validation is wrong. Can be of any data type, example here is using type number.",
                        "example": 12345
                      },
                      "property": {
                        "type": "string",
                        "description": "Property name of the target object which validation is wrong",
                        "example": "property1"
                      },
                      "constraints": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Object of failed constraints for the target object. Key is the constraint, value is detailed description of the failed constraint.",
                        "example": {
                          "min": "property1 must not be less than 50000"
                        }
                      }
                    }
                  }
                }
              },
              "required": [
                "errorCode",
                "message",
                "statusCode",
                "data"
              ],
              "type": "object"
            }
          }
        }
      },
      "Error401": {
        "description": "Unauthorized. Not valid or inactive subscription key present in the HTTP Header.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "properties": {
                    "errorCode": {
                      "example": "subscription.not.active",
                      "description": "subscription.not.active",
                      "type": "string"
                    },
                    "message": {
                      "example": "Subscription not active anymore.",
                      "description": "Subscription not active anymore.",
                      "type": "string"
                    },
                    "statusCode": {
                      "example": 401,
                      "description": "401",
                      "type": "number"
                    }
                  },
                  "required": [
                    "errorCode",
                    "message",
                    "statusCode"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "errorCode": {
                      "example": "subscription.invalid",
                      "description": "subscription.invalid",
                      "type": "string"
                    },
                    "message": {
                      "example": "Unable to find valid subscription for '${apiKey}'",
                      "description": "Unable to find valid subscription for '${apiKey}'",
                      "type": "string"
                    },
                    "statusCode": {
                      "example": 401,
                      "description": "401",
                      "type": "number"
                    }
                  },
                  "required": [
                    "errorCode",
                    "message",
                    "statusCode"
                  ],
                  "type": "object"
                }
              ]
            }
          }
        }
      },
      "Error403": {
        "description": "Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "message": {
                  "example": "Forbidden",
                  "description": "Forbidden",
                  "type": "string"
                },
                "statusCode": {
                  "example": 403,
                  "description": "403",
                  "type": "number"
                }
              },
              "required": [
                "statusCode",
                "message"
              ],
              "type": "object"
            }
          }
        }
      },
      "Error500": {
        "description": "Internal server error. There was an error on the server during the processing of the request.",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "message": {
                  "example": "Internal server error",
                  "description": "Internal server error",
                  "type": "string"
                },
                "statusCode": {
                  "example": 500,
                  "description": "500",
                  "type": "number"
                }
              },
              "required": [
                "statusCode",
                "message"
              ],
              "type": "object"
            }
          }
        }
      }
    },
    "schemas": {
      "PredictionPlatform": {
        "type": "string",
        "description": "Prediction-market platform identifier.",
        "enum": [
          "polymarket",
          "kalshi"
        ],
        "example": "polymarket"
      },
      "PredictionHistoryInterval": {
        "type": "string",
        "description": "OHLC candle bucket size. Each interval has its own maximum allowed time window;\nrequests exceeding that window return `400`.\n",
        "enum": [
          "1m",
          "5m",
          "15m",
          "1h",
          "4h",
          "1d",
          "1w"
        ],
        "example": "1h"
      },
      "PredictionHistorySource": {
        "type": "string",
        "description": "Underlying data feed for OHLC candles. `candlesticks` (default) is trade-based\nwith real in-bucket volume. `midpoint` uses a midpoint-quote feed with broader\ntime-range coverage at the cost of `volume = 0` on every candle. `midpoint`\nis Polymarket-only.\n",
        "enum": [
          "candlesticks",
          "midpoint"
        ],
        "example": "candlesticks"
      },
      "PredictionPriceCandle": {
        "type": "object",
        "description": "A single OHLC candle.",
        "required": [
          "timestamp",
          "open",
          "high",
          "low",
          "close",
          "volume"
        ],
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 bucket-aligned start time of the candle.",
            "example": "2026-05-18T12:00:00Z"
          },
          "open": {
            "type": "number",
            "description": "Opening price of the bucket.",
            "example": 0.41
          },
          "high": {
            "type": "number",
            "description": "Highest price within the bucket.",
            "example": 0.44
          },
          "low": {
            "type": "number",
            "description": "Lowest price within the bucket.",
            "example": 0.4
          },
          "close": {
            "type": "number",
            "description": "Closing price of the bucket.",
            "example": 0.43
          },
          "volume": {
            "type": "number",
            "description": "In-bucket trade volume. Always `0` when `source=midpoint` (the midpoint feed\ncarries no volume data).\n",
            "example": 12450.5
          }
        }
      },
      "PredictionPriceHistory": {
        "type": "object",
        "description": "Historical OHLC candles for a market over a time window.",
        "required": [
          "marketId",
          "platform",
          "interval",
          "source",
          "candles",
          "partial",
          "availableFrom"
        ],
        "properties": {
          "marketId": {
            "type": "string",
            "description": "Platform-native market identifier.",
            "example": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917"
          },
          "platform": {
            "$ref": "#/components/schemas/PredictionPlatform"
          },
          "interval": {
            "$ref": "#/components/schemas/PredictionHistoryInterval"
          },
          "source": {
            "$ref": "#/components/schemas/PredictionHistorySource"
          },
          "candles": {
            "type": "array",
            "description": "Candles in chronological order, bucket-aligned to `interval`.",
            "items": {
              "$ref": "#/components/schemas/PredictionPriceCandle"
            }
          },
          "partial": {
            "type": "boolean",
            "description": "`true` when the requested range was truncated by an upstream availability\nlimit. When `true`, `availableFrom` indicates the earliest timestamp the\nresponse actually covers.\n",
            "example": false
          },
          "availableFrom": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Earliest timestamp the response covers. Equals the requested `start` when\n`partial` is `false`. `null` when no trades exist in the entire requested\nrange.\n",
            "example": "2026-05-01T00:00:00Z"
          }
        }
      },
      "PredictionPriceHistoryResponse": {
        "type": "object",
        "description": "Price-history response.",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PredictionPriceHistory"
          }
        }
      }
    }
  }
}
```