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

# REST API

> The REST half of the TakeProfit Platform API: base URL, the x-api-key header, the query parameters every history endpoint shares, what each endpoint returns, and the error codes.

Historical market data and the security catalog over plain HTTP. Every endpoint answers `GET` only, returns JSON, and takes the API key in the `x-api-key` header.

```bash theme={null}
curl -G "https://public-api.takeprofit.com/api/v1/marketdata/candles" \
  -H "x-api-key: $TAKEPROFIT_API_KEY" \
  --data-urlencode "exchange=CXBNCE" \
  --data-urlencode "symbol=BTC/USDT" \
  --data-urlencode "timeframe=1h" \
  --data-urlencode "from=2026-09-01T00:00:00Z" \
  --data-urlencode "limit=100"
```

Base URL: `https://public-api.takeprofit.com/api/v1/marketdata`. Live data is a separate protocol — see the [WebSocket API](/docs/platform-api/websocket/overview).

## Endpoints

| Group | Endpoint | Returns |
| - | - | - |
| **Candles** | `GET /candles` | Historical candles for one security and timeframe. |
| | `GET /timeframes` | Every supported timeframe id, with the count rules that build them. |
| **Footprint** | `GET /footprint` | Volume footprint profiles: buy and sell volume and trade counts per price row. |
| | `GET /footprint/row-size-scale` | The row size step and bounds a settings UI can offer for a security and timeframe. |
| **TPO** | `GET /tpo` | TPO (Market Profile) profiles with point of control, initial balance and time blocks. |
| **Securities** | `GET /search` | Ranked search over securities by text or exact ISIN. |
| | `GET /exchanges` | Exchanges that have publicly served securities. |
| | `GET /exchanges/{exchange}/securities` | Securities listed on one exchange. |
| | `GET /exchanges/{exchange}/securities/{symbol}` | One security specification: type, assets, tick size, precision. |

Each endpoint page in the sidebar lists its parameters and response fields and has a **Try it** playground.

<Note>
  **Only `exchange`, `symbol` and `timeframe` are required.** Leave the range out and the endpoint answers with the most recent data it has — the last 1000 candles, or the profiles that fit the default window. Add `from`, `to`, `period` or `limit` to narrow it down.

  **Exchange codes come from `GET /exchanges`.** They are TakeProfit codes, not the MIC of the listing venue: US equities are served under `BATS`, so `AAPL` lives at `exchange=BATS`. An unknown code answers `404 exchange not found`, a symbol that is not listed there `404 security not found`.
</Note>

## Parameters the history endpoints share

| Parameter | Applies to | Notes |
| - | - | - |
| `exchange`, `symbol` | all data endpoints | Required. Take the pair from the Securities endpoints; ISINs work in search only. |
| `timeframe` | candles, footprint, TPO | Required. Ids come from `GET /timeframes`. Footprint takes minute to month frames, TPO only day, week and month frames. |
| `from` | candles, footprint, TPO | Optional. Unix seconds or an RFC3339 timestamp. Left out, the window is measured backwards from `to`. |
| `to` | candles, footprint, TPO | Optional, and greater than `from`. Defaults to now when `from` is omitted. |
| `period` | candles, footprint, TPO | Optional duration **in seconds** (`86400`, not `1d`), counted forward from `from` or backwards from `to`. Not available on tick timeframes. |
| `limit` | candles | Optional candle count, counted from whichever end of the range you pinned. **Defaults to 1000**, and is the only range control tick timeframes accept. |
| `sessionType` | candles, footprint, TPO | Optional filter: `MAINSESSION`, `PRE_MARKET`, `POST_MARKET`. Repeat the parameter or pass comma-separated values. |
| `rowSize`, `rowSizeValue` | footprint | Price row height in ticks, or an absolute value echoed back from a previous response to pin the same price grid. |
| `blockSize`, `mergeSessions` | TPO | Time block duration as a timeframe id (default `30m`, not seconds) and whether sessions merge into one profile per period. |

Combine what you need: `from` alone reads forward from that point, `to` alone reads backwards from it, `from` with `to` pins both ends, and `period` sets the length from whichever end you gave. Unknown query parameters are still rejected with `400`, so a typo fails loudly instead of being silently ignored — passing `limit` to footprint or TPO is one of those typos, since only candles take it.

Every response carries the rate-limit headers `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (the reset is a Unix timestamp), plus an `x-request-id` worth quoting in a support request.

## Reading the responses

* **Prices and volumes are decimal strings.** Nothing is rounded into a float on the way to you.
* **Profile rows are positional arrays.** A footprint row is `[price, volumeBuy, volumeSell, tradesCountBuy, tradesCountSell]`, a TPO row is `[price, blockIndexes, volumeBuy, volumeSell]`. Future fields are appended, so ignore extra trailing elements.
* **`price` is the lower bound** of the half-open interval `[price, price + rowSize)`.
* **History depth is limited per timeframe** for footprint and TPO, counted back from the security's newest candle: 30 days for minute frames below `5m`, rising with the timeframe to 3 years for `1w` and above. A `from` older than the limit is trimmed rather than rejected, so the response can start later than you asked, and a range that ends before the limit comes back empty.

## Errors

Every failure returns an HTTP status and a JSON body.

| Status | Meaning |
| - | - |
| `400` | Invalid or unknown query parameter |
| `401` | Missing or invalid API key |
| `403` | The key has no access to this data |
| `404` | Security or data not found |
| `429` | Credit quota exhausted |
| `502`, `503`, `504` | Temporary upstream problem, retry later |

New here? [Quickstart](/docs/platform-api/quickstart) walks through the first three requests, and [Authentication](/docs/platform-api/authentication) covers creating a key.