> ## Documentation Index > Fetch the complete documentation index at: https://api-portal.etoro.com/llms.txt > Use this file to discover all available pages before exploring further. # Get price candles for an instrument > **Rate limit:** 120 requests per 60 seconds. This is a **shared quota** — the same budget is consumed by a group of related endpoints, so calling any of them reduces what is left for the others (you cannot call each at the full rate independently). Endpoints sharing this quota: - `GET /api/v1/data/instruments/{instrumentId}/candles/coverage` --- Full-history OHLC candles for one instrument and interval, from a public view built and kept current by a DataPlatform job. Not user-scoped: identical for every caller for the same instrument and parameters. A range without `from` returns the most recent slice; a slice covers at most 10,080 periods of the interval (7 days of 1m, up to all history for 1d/1w), and a longer range is paged with the keyset `cursor` in `pagination.nextCursor`. An instrument with no data for the interval, or one eToro shows internally only, returns 200 with an empty `results` array, not 404. Call the coverage endpoint first to find a range that has data. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/data/instruments/{instrumentId}/candles openapi: 3.0.1 info: title: eToro Api version: v1.383.0 description: >- eToro’s public API provides access to real-time financial data, trading insights, and account management features, allowing developers to integrate eToro’s services into their applications. With access to market prices, historical data, and social trading information, the API empowers users to enhance their trading strategies. Designed for security and scalability, the eToro API ensures smooth and reliable integration for a variety of financial applications. For more details on integrating with eToro's public WebSocket service, please refer to the dedicated [WebSocket documentation](./websocket/websocket-doc.html). ## Authentication Every request must be authenticated with exactly one of two options: an OAuth 2.0 access token (`Authorization: Bearer `), or the non-interactive credential pair (`x-api-key` + `x-user-key` headers). The two options are mutually exclusive — a request carrying both is rejected. Each operation lists the OAuth scopes that grant access as alternative security requirements: a bearer token needs only ONE of them, and the same permissions govern the credential pair. servers: - url: https://public-api.etoro.com description: eToro Public API security: - apiKeyAuth: [] userKeyAuth: [] - oauth2: [] tags: - name: Agent Portfolios - name: Social Feeds - name: Balances - name: Clubs - name: Watchlists - name: Data - name: Top Assets - name: App Data - name: Market Data - name: Identity - name: Cash Accounts - name: Transfer - name: Notifications - name: PI Data - name: PortfolioSearch - name: Price Alerts - name: SSO - Applications - name: SSO - Scopes - name: Sub-Accounts - eToro Trading - name: Sub-Accounts - name: Trading - Demo - name: Trading - Real - name: Users Info - name: Rankings - name: User Stats - name: Copy Trading - name: Copy Trading - Demo paths: /api/v1/data/instruments/{instrumentId}/candles: get: tags: - Data summary: Get price candles for an instrument description: >- **Rate limit:** 120 requests per 60 seconds. This is a **shared quota** — the same budget is consumed by a group of related endpoints, so calling any of them reduces what is left for the others (you cannot call each at the full rate independently). Endpoints sharing this quota: - `GET /api/v1/data/instruments/{instrumentId}/candles/coverage` --- Full-history OHLC candles for one instrument and interval, from a public view built and kept current by a DataPlatform job. Not user-scoped: identical for every caller for the same instrument and parameters. A range without `from` returns the most recent slice; a slice covers at most 10,080 periods of the interval (7 days of 1m, up to all history for 1d/1w), and a longer range is paged with the keyset `cursor` in `pagination.nextCursor`. An instrument with no data for the interval, or one eToro shows internally only, returns 200 with an empty `results` array, not 404. Call the coverage endpoint first to find a range that has data. operationId: getPriceCandles parameters: - name: x-request-id in: header required: true schema: type: string format: uuid example: e0245e0b-362b-4f73-85e7-43a7cfb2a9e9 description: A unique request identifier. example: e0245e0b-362b-4f73-85e7-43a7cfb2a9e9 - name: instrumentId in: path required: true schema: type: integer format: int32 minimum: 1 description: eToro instrument id, e.g. 1001 for AAPL. - name: interval in: query required: true schema: type: string enum: - 1m - 5m - 10m - 15m - 30m - 1h - 4h - 1d - 1w description: Candle interval. - name: from in: query required: false schema: type: string format: date-time description: >- Inclusive lower bound on candle open time, ISO 8601 with a time zone. Defaults to one slice before `to`. - name: to in: query required: false schema: type: string format: date-time description: >- Exclusive upper bound on candle open time, ISO 8601 with a time zone. Defaults to now. - name: limit in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 2000 default: 100 description: Candles per page. Defaults to 100, maximum 2000. - name: side in: query required: false schema: type: string enum: - bid - ask - both default: bid description: Price side to return. Defaults to bid. - name: format in: query required: false schema: type: string enum: - verbose - compact default: verbose description: >- `compact` names each column once; `results` becomes one array per candle instead of an object. - name: cursor in: query required: false schema: type: string description: Opaque token from `pagination.nextCursor`. responses: '200': description: >- One page of candles for the requested instrument and interval, newest first unless walking an older slice. content: application/json: schema: $ref: '#/components/schemas/PriceCandlesPage' example: instrumentId: 1001 symbol: AAPL interval: 1d side: bid window: from: '2026-09-01T00:00:00Z' to: '2026-09-28T00:00:00Z' pagination: limit: 100 hasNext: false nextCursor: null results: - time: '2026-09-27T21:00:00Z' open: '228.5' high: '231.2' low: '227.9' close: '230.1' volume: '1234567' headers: X-Correlation-Id: schema: type: string format: uuid description: >- Correlation id for this call, generated by the data platform upstream when the request arrives without one and identical end to end. Quote it to eToro support to find the request in logs. X-Request-Id: schema: type: string format: uuid description: >- Echoed back only when the caller supplied it. The upstream never generates one. X-Timestamp: schema: type: string format: date-time description: RFC 3339 instant the response was produced. Cache-Control: schema: type: string description: >- Always `public, max-age=30` -- this is market data, not customer-scoped. example: public, max-age=30 RateLimit-Limit: description: >- Maximum number of requests allowed per window. This budget is SHARED across 2 endpoints (it is NOT per-endpoint): a request to any endpoint in the group spends the same budget. See this operation's description for the full list of endpoints sharing it. schema: type: integer example: 120 RateLimit-Remaining: description: Requests remaining in the current window for this quota. schema: type: integer RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer RateLimit-Policy: description: Quota policy in the form `;w=`. schema: type: string example: 120;w=60 '400': description: >- Invalid parameters -- an out-of-range interval, a malformed timestamp without a time zone, `from` not earlier than `to`, or an unrecognized cursor. content: application/json: schema: $ref: '#/components/schemas/DataApiError' example: success: false error: code: INVALID_TIME_RANGE message: '`from` must be earlier than `to`' headers: X-Correlation-Id: schema: type: string format: uuid description: >- Correlation id for this call, generated by the data platform upstream when the request arrives without one and identical end to end. Quote it to eToro support to find the request in logs. X-Request-Id: schema: type: string format: uuid description: >- Echoed back only when the caller supplied it. The upstream never generates one. X-Timestamp: schema: type: string format: date-time description: RFC 3339 instant the response was produced. Cache-Control: schema: type: string description: >- Always `public, max-age=30` -- this is market data, not customer-scoped. example: public, max-age=30 '429': description: >- Too Many Requests — the shared rate limit (120 requests / 60s) was exceeded. headers: RateLimit-Limit: description: >- Maximum number of requests allowed per window. This budget is SHARED across 2 endpoints (it is NOT per-endpoint): a request to any endpoint in the group spends the same budget. See this operation's description for the full list of endpoints sharing it. schema: type: integer example: 120 RateLimit-Remaining: description: Requests remaining in the current window for this quota. schema: type: integer RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer RateLimit-Policy: description: Quota policy in the form `;w=`. schema: type: string example: 120;w=60 Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 '503': description: >- The serving dependency is temporarily unavailable; the upstream already retried with backoff before returning this. Safe to retry. content: application/json: schema: $ref: '#/components/schemas/DataApiError' example: success: false error: code: DEPENDENCY_UNAVAILABLE message: The requested resource is temporarily unavailable headers: X-Correlation-Id: schema: type: string format: uuid description: >- Correlation id for this call, generated by the data platform upstream when the request arrives without one and identical end to end. Quote it to eToro support to find the request in logs. X-Request-Id: schema: type: string format: uuid description: >- Echoed back only when the caller supplied it. The upstream never generates one. X-Timestamp: schema: type: string format: date-time description: RFC 3339 instant the response was produced. Cache-Control: schema: type: string description: >- Always `public, max-age=30` -- this is market data, not customer-scoped. example: public, max-age=30 security: - apiKeyAuth: [] userKeyAuth: [] - oauth2: - etoro-public:real:read - oauth2: - etoro-public:demo:read - oauth2: - etoro-public:real:write - oauth2: - etoro-public:demo:write - oauth2: - etoro-public:market-data:read components: schemas: PriceCandlesPage: type: object description: One page of price candles for a single instrument and interval. properties: instrumentId: type: integer format: int32 symbol: type: string nullable: true description: Instrument display name, e.g. AAPL/USD. Null when the page is empty. interval: type: string enum: - 1m - 5m - 10m - 15m - 30m - 1h - 4h - 1d - 1w side: type: string enum: - bid - ask - both window: $ref: '#/components/schemas/TimeWindow' pagination: $ref: '#/components/schemas/CursorPagination' results: type: array items: $ref: '#/components/schemas/PriceCandle' required: - instrumentId - symbol - interval - side - window - pagination - results DataApiError: type: object description: >- Error envelope returned by the data platform upstream. Response metadata is not in the body: the correlation id, the request id and the timestamp are returned as the `X-Correlation-Id`, `X-Request-Id` and `X-Timestamp` response headers. Quote `X-Correlation-Id` to eToro support to find the request in logs. properties: success: type: boolean description: Always false on an error response. example: false error: type: object properties: code: type: string description: Stable machine-readable error code, UPPER_SNAKE_CASE. message: type: string description: >- Human-readable description. Not intended for display to end users. required: - code - message required: - success - error TimeWindow: type: object description: 'The requested time range, after defaults: [from, to).' properties: from: type: string format: date-time description: Inclusive lower bound, UTC. to: type: string format: date-time description: Exclusive upper bound, UTC. required: - from - to CursorPagination: type: object description: >- Keyset pagination metadata for a time-ordered collection. `hasNext` is always present; `nextCursor` is opaque and is null exactly when `hasNext` is false. properties: limit: type: integer format: int32 description: Maximum number of items that could be returned on this page. example: 100 hasNext: type: boolean description: Whether a further page exists after this one. example: false nextCursor: type: string nullable: true description: >- Opaque token for the next page; pass it back unchanged as `cursor`. Null when there is no further page. required: - limit - hasNext - nextCursor PriceCandle: type: object description: One candle for a single price side (`side=bid` or `side=ask`). properties: time: type: string format: date-time description: Candle open time, UTC. open: type: string nullable: true description: First price in the candle, as an exact decimal string. high: type: string nullable: true description: Highest price in the candle. low: type: string nullable: true description: Lowest price in the candle. close: type: string nullable: true description: Last price in the candle. volume: type: string nullable: true description: >- Source volume, passed through. Frequently null; null means not reported. required: - time - open - high - low - close - volume securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key of the application. Only valid together with the x-user-key header — the pair is an alternative to OAuth bearer authentication, never sent alongside it. The pair is granted the same permissions the operation's OAuth scopes describe. Demo credential for trying the API from these docs: `lhgfaslk21490FAScVPkdsb53F9dNkfHG4faZSG5vfjndfcfgdssdgsdHF4663` userKeyAuth: type: apiKey in: header name: x-user-key description: >- User-specific authentication key. Only valid together with the x-api-key header — the pair is an alternative to OAuth bearer authentication, never sent alongside it. Demo credential for trying the API from these docs: `eyJlYW4iOiJVbnJlZ2lzdGVyZWRBcHBsaWNhdGlvbiIsImVrIjoiOE5sZ2cwcW5EUVdROUFNWGpXT2lmOWktZnpidG5KcUlqWGJ3WHJZZkpZcldrbG90ZEhvLVBjSWhQaU8xU1ZtMW84aU1WZGZqN2xWNzFjLXFxLmcybXE1dnh4Q1hUT25xaWRUaTFlcEhmVk1fIn0_` oauth2: type: oauth2 description: >- eToro OAuth2 — send the access token as `Authorization: Bearer `. Each operation lists the scopes that grant access as separate `security` requirements (OpenAPI OR semantics): the caller's token only needs ONE of them — you do NOT need all of them. Mutually exclusive with the x-api-key/x-user-key credential pair: never send both. flows: authorizationCode: authorizationUrl: https://www.etoro.com/sso tokenUrl: https://www.etoro.com/api/sso/v1/token scopes: etoro-public:agent-portfolio:read: Grants access to the 'etoro-public:agent-portfolio:read' scope. etoro-public:agent-portfolio:write: Grants access to the 'etoro-public:agent-portfolio:write' scope. etoro-public:club:read: Grants access to the 'etoro-public:club:read' scope. etoro-public:demo:read: Grants access to the 'etoro-public:demo:read' scope. etoro-public:demo:write: Grants access to the 'etoro-public:demo:write' scope. etoro-public:feed:read: Grants access to the 'etoro-public:feed:read' scope. etoro-public:feed:write: Grants access to the 'etoro-public:feed:write' scope. etoro-public:market-data:read: Grants access to the 'etoro-public:market-data:read' scope. etoro-public:money.balance:read: Grants access to the 'etoro-public:money.balance:read' scope. etoro-public:money.cash-transactions:read: >- Grants access to the 'etoro-public:money.cash-transactions:read' scope. etoro-public:money.transfer:read: Grants access to the 'etoro-public:money.transfer:read' scope. etoro-public:money.transfer:write: Grants access to the 'etoro-public:money.transfer:write' scope. etoro-public:money:transfer: Grants access to the 'etoro-public:money:transfer' scope. etoro-public:notifications:read: Grants access to the 'etoro-public:notifications:read' scope. etoro-public:notifications:write: Grants access to the 'etoro-public:notifications:write' scope. etoro-public:pi-data:read: Grants access to the 'etoro-public:pi-data:read' scope. etoro-public:price-alerts:read: Grants access to the 'etoro-public:price-alerts:read' scope. etoro-public:price-alerts:write: Grants access to the 'etoro-public:price-alerts:write' scope. etoro-public:real:read: Grants access to the 'etoro-public:real:read' scope. etoro-public:real:write: Grants access to the 'etoro-public:real:write' scope. etoro-public:sso-applications:read: Grants access to the 'etoro-public:sso-applications:read' scope. etoro-public:sso-applications:write: Grants access to the 'etoro-public:sso-applications:write' scope. etoro-public:sso-scopes:read: Grants access to the 'etoro-public:sso-scopes:read' scope. etoro-public:sso-scopes:write: Grants access to the 'etoro-public:sso-scopes:write' scope. etoro-public:sub-accounts:read: Grants access to the 'etoro-public:sub-accounts:read' scope. etoro-public:sub-accounts:write: Grants access to the 'etoro-public:sub-accounts:write' scope. etoro-public:trade.demo:read: Grants access to the 'etoro-public:trade.demo:read' scope. etoro-public:trade.demo:write: Grants access to the 'etoro-public:trade.demo:write' scope. etoro-public:trade.real:read: Grants access to the 'etoro-public:trade.real:read' scope. etoro-public:trade.real:write: Grants access to the 'etoro-public:trade.real:write' scope. etoro-public:user-info:read: Grants access to the 'etoro-public:user-info:read' scope. etoro-public:watchlist:read: Grants access to the 'etoro-public:watchlist:read' scope. etoro-public:watchlist:write: Grants access to the 'etoro-public:watchlist:write' scope. ````