> ## 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. # List historical candles > Provide `exchange`, `symbol`, and `timeframe`. Nothing else is required: the window defaults to the last 1000 candles. - With `from` the window starts there and runs forward, ending at `to`, after `period` seconds, or after `limit` candles (1000 by default). - Without `from` the window ends at `to` (now by default) and runs backwards over `limit` candles (1000 by default) or `period` seconds. - `period` and `limit` cannot be used together, and neither can be added to an explicit `from`+`to` window. - Tick timeframes accept `from` and `limit` only. - A request is limited to at most 10000 estimated candles. **Cost:** 1 credit per returned candle, at least 1000 credits per request. ## OpenAPI ````yaml /platform-api/specs/openapi.yaml get /api/v1/marketdata/candles openapi: 3.0.3 info: title: TakeProfit API (REST) version: 0.6.0 contact: email: support@takeprofit.com description: | Historical marketdata and the security catalog over REST. Live streams (candles, volume footprint, order books) are served over WebSocket and described by the AsyncAPI document at `https://public-api.takeprofit.com/api/v1/marketdata/asyncapi.yaml`. Guides (getting an API key, credits and quota, errors) live at [takeprofit.com/docs](https://takeprofit.com/docs). ## Requests - Base URL: `https://public-api.takeprofit.com`. - Every endpoint answers `GET` only. - Authenticate with the `x-api-key` header; exactly one header value is required. - Unknown query parameters and repeated scalar parameters are rejected with 400. - Identify securities with `exchange` and `symbol` as returned by the catalog endpoints; internal ids and GUIDs are not accepted (search additionally accepts an ISIN as a lookup key). ## Credits and quota Requests are metered in credits against a fixed quota window of 100000 credits per 60 seconds, shared by all API keys of the account. Each operation states its price; every billed request costs at least 1000 credits, so an account makes at most 100 requests per minute. Every authenticated response carries the window state: - `X-RateLimit-Limit` - credits per window; - `X-RateLimit-Remaining` - credits still available after this request; - `X-RateLimit-Reset` - epoch second the window resets at. A request the remaining credits cannot cover is rejected with 429 and `Retry-After` (seconds until the window resets); the rejection itself is free. ## Errors Every error response is `{"error": {"code": "", "message": ""}}`. The statuses listed on each operation (400, 401, 403, 404, 429) are the outcomes a client handles explicitly. A 400 is either `invalid_argument` (a malformed request) or `too_much_data`: the request produces more data than can be served in one response, and only a narrower window fixes it - it is never a rate limit. In addition, any operation can answer 502 (`bad_gateway`), 503 (`unavailable`) or 504 (`deadline_exceeded`) while the gateway or an upstream is unavailable or slow; these are transient - retry with exponential backoff. servers: - url: https://public-api.takeprofit.com description: Production security: [] paths: /api/v1/marketdata/candles: get: tags: - Candles summary: List historical candles description: > Provide `exchange`, `symbol`, and `timeframe`. Nothing else is required: the window defaults to the last 1000 candles. - With `from` the window starts there and runs forward, ending at `to`, after `period` seconds, or after `limit` candles (1000 by default). - Without `from` the window ends at `to` (now by default) and runs backwards over `limit` candles (1000 by default) or `period` seconds. - `period` and `limit` cannot be used together, and neither can be added to an explicit `from`+`to` window. - Tick timeframes accept `from` and `limit` only. - A request is limited to at most 10000 estimated candles. **Cost:** 1 credit per returned candle, at least 1000 credits per request. operationId: listCandles parameters: - name: exchange in: query required: true schema: $ref: '#/components/schemas/ExchangeCode' - name: symbol in: query required: true description: >- Public security symbol returned by /api/v1/marketdata/exchanges/{exchange}/securities. schema: $ref: '#/components/schemas/SecuritySymbol' - name: timeframe in: query required: true schema: $ref: '#/components/schemas/TimeframeId' - name: from in: query required: false description: >- Range start as Unix seconds or RFC3339 timestamp. Without it the window is measured backwards from to. schema: $ref: '#/components/schemas/TimestampQuery' - name: to in: query required: false description: >- Range end as Unix seconds or RFC3339 timestamp, greater than from. Defaults to now when from is omitted. Not supported for tick timeframes. schema: $ref: '#/components/schemas/TimestampQuery' - name: period in: query required: false description: >- Range duration in seconds, counted forward from from or backwards from to. Not supported for tick timeframes. schema: $ref: '#/components/schemas/PositiveSeconds' - name: limit in: query required: false description: >- Candle count to return, counted forward from from or backwards from to. Defaults to 1000. schema: type: integer minimum: 1 maximum: 10000 - name: sessionType in: query required: false description: >- Optional session filter. Repeat this parameter or pass comma-separated values. style: form explode: true schema: type: array items: $ref: '#/components/schemas/SessionType' responses: '200': description: Candles response. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/CandlesResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' security: - ApiKeyAuth: [] components: schemas: ExchangeCode: type: string description: TakeProfit exchange code as returned by /api/v1/marketdata/exchanges. example: BATS SecuritySymbol: type: string description: >- TakeProfit security symbol as returned by /api/v1/marketdata/exchanges/{exchange}/securities. In a path segment a slash must be percent-encoded (BTC/USDT is requested as BTC%2FUSDT). example: AAPL TimeframeId: type: string description: >- Timeframe id returned by /api/v1/marketdata/timeframes. Canonical suffixes include M for months and Q for quarters. example: 1h TimestampQuery: type: string description: Unix seconds (for example 1790000000) or RFC3339 timestamp. PositiveSeconds: type: integer minimum: 1 SessionType: type: string enum: - MAINSESSION - PRE_MARKET - POST_MARKET CandlesResponse: type: object required: - meta - candles properties: meta: $ref: '#/components/schemas/CandlesMeta' candles: type: array items: $ref: '#/components/schemas/Candle' example: meta: exchange: BATS symbol: AAPL timeframe: 1m candles: - timestamp: '2026-09-21T13:30:00Z' open: '335.28' high: '335.54' low: '333.66' close: '333.97' volume: '12895' sessionType: MAINSESSION - timestamp: '2026-09-21T13:31:00Z' open: '333.92' high: '334.52' low: '333.66' close: '334.07' volume: '4172' sessionType: MAINSESSION CandlesMeta: type: object required: - exchange - symbol - timeframe properties: exchange: $ref: '#/components/schemas/ExchangeCode' symbol: $ref: '#/components/schemas/SecuritySymbol' timeframe: $ref: '#/components/schemas/TimeframeId' Candle: type: object required: - timestamp - open - high - low - close - volume - sessionType properties: timestamp: type: string format: date-time open: type: string high: type: string low: type: string close: type: string volume: type: string sessionType: $ref: '#/components/schemas/SessionType' ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable public error code. message: type: string description: Human-readable public error message. example: error: code: unauthenticated message: authentication failed headers: RateLimitLimit: description: Credits allowed per quota window. schema: type: integer RateLimitRemaining: description: Credits still available in the current quota window after this request. schema: type: integer RateLimitReset: description: Epoch second at which the current quota window resets. schema: type: integer format: int64 RetryAfter: description: Seconds until the quota window resets and the request can be retried. schema: type: integer responses: InvalidRequest: description: >- Invalid request (`invalid_argument`), or a request producing more data than can be served (`too_much_data`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_argument message: query parameter "exchange" is required Unauthorized: description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthenticated message: authentication failed Forbidden: description: Permission denied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: permission_denied message: permission denied NotFound: description: The exchange or the security is not served. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: not_found message: security not found RateLimited: description: >- The remaining credits of the quota window cannot cover this request; retry after the window resets. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limited message: rate limit exceeded securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````