> ## 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 user watchlists

> Retrieves all watchlists for the authenticated user with optional pagination and built-in watchlist management.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/watchlists
openapi: 3.0.1
info:
  title: eToro Api
  version: v1.206.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).
servers:
  - url: https://public-api.etoro.com
    description: eToro Public API
security: []
tags:
  - name: Agent Portfolios
  - name: Watchlists
  - name: Feeds
  - name: Asset Explorer
  - name: Market Data
  - name: Identity
  - name: Notifications
  - name: PI Data
  - name: Comments
  - name: Trading Demo
  - name: Trading Real
  - name: Users Info
  - name: Deprecated
paths:
  /api/v1/watchlists:
    get:
      tags:
        - Watchlists
      summary: Get user watchlists
      description: >-
        Retrieves all watchlists for the authenticated user with optional
        pagination and built-in watchlist management.
      operationId: getUserWatchlists
      parameters:
        - name: x-request-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
            example: f235698a-f7df-41e9-9f26-9d3b62c7432a
          description: A unique request identifier.
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
            format: password
            example: lhgfaslk21490FAScVPkdsb53F9dNkfHG4faZSG5vfjndfcfgdssdgsdHF4663
          description: API key for authentication.
        - name: x-user-key
          in: header
          required: true
          schema:
            type: string
            format: password
            example: >-
              eyJlYW4iOiJVbnJlZ2lzdGVyZWRBcHBsaWNhdGlvbiIsImVrIjoiOE5sZ2cwcW5EUVdROUFNWGpXT2lmOWktZnpidG5KcUlqWGJ3WHJZZkpZcldrbG90ZEhvLVBjSWhQaU8xU1ZtMW84aU1WZGZqN2xWNzFjLXFxLmcybXE1dnh4Q1hUT25xaWRUaTFlcEhmVk1fIn0_
          description: User-specific authentication key.
        - name: itemsPerPageForSingle
          in: query
          description: Number of items to include per watchlist for pagination
          schema:
            type: integer
            format: int32
            default: 100
            minimum: 1
            maximum: 1000
            example: 100
        - name: ensureBuiltinWatchlists
          in: query
          description: Whether to ensure built-in watchlists are included
          schema:
            type: boolean
            default: true
            example: true
        - name: addRelatedAssets
          in: query
          description: Whether to include related assets in the response
          schema:
            type: boolean
            default: false
            example: false
      responses:
        '200':
          description: Successfully retrieved user watchlists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistsResponse'
components:
  schemas:
    WatchlistsResponse:
      type: object
      description: Response containing multiple watchlists with metadata
      properties:
        status:
          type: integer
          format: int32
          description: HTTP status code of the response
          example: 200
        watchlists:
          type: array
          description: List of user watchlists
          items:
            $ref: '#/components/schemas/WatchlistResponse'
        exception:
          type: object
          description: Exception details when the request partially failed
          properties:
            invalidItems:
              type: array
              description: List of invalid item identifiers
              items:
                type: string
            reason:
              type: string
              description: Reason for the exception
            message:
              type: string
              description: Human-readable exception message
        meta:
          type: object
          description: Response metadata including pagination info
          properties:
            pageNumber:
              type: integer
              format: int32
              description: Current page number
              example: 0
            itemsPerPage:
              type: integer
              format: int32
              description: Number of items per page
              example: 100
            maxItemsInWatchlistLimit:
              type: integer
              format: int32
              description: Maximum allowed items per watchlist
              example: 1000
            maxWatchlistsLimit:
              type: integer
              format: int32
              description: Maximum allowed watchlists per user
              example: 10
        isSucceeded:
          type: boolean
          description: Whether the request succeeded
          example: true
    WatchlistResponse:
      type: object
      description: Represents a watchlist with its metadata and items
      properties:
        watchlistId:
          type: string
          description: Unique identifier of the watchlist
          example: '12345'
        name:
          type: string
          description: Display name of the watchlist
          example: Tech Watchlist
        Gcid:
          type: integer
          format: int32
          description: Global Customer ID of the watchlist owner
          example: 12345
        watchlistType:
          type: string
          enum:
            - Static
            - Dynamic
            - RecentlyInvested
            - Default
          description: Type of the watchlist
          example: Static
        totalItems:
          type: integer
          format: int32
          description: Total number of items in the watchlist
          example: 100
        isDefault:
          type: boolean
          description: Whether this is a default system watchlist
          example: true
        isUserSelectedDefault:
          type: boolean
          description: Whether this is the user's selected default watchlist
          example: true
        watchlistRank:
          type: integer
          format: int32
          description: Display order rank of the watchlist
          example: 1
        dynamicUrl:
          type: string
          nullable: true
          description: URL for dynamic watchlist queries
        items:
          type: array
          description: Items contained in the watchlist
          items:
            $ref: '#/components/schemas/WatchlistItemDto'
          example:
            - itemId: 12345
              itemType: Instrument
              itemRank: 1
        relatedAssets:
          type: array
          description: Related asset IDs
          nullable: true
          items:
            type: integer
            format: int32
          example:
            - 12345
            - 67890
    WatchlistItemDto:
      type: object
      description: Represents an item in a watchlist
      required:
        - itemId
        - itemType
      properties:
        itemId:
          type: integer
          format: int32
          description: Unique identifier of the financial instrument
          example: 12345
        itemType:
          type: string
          description: Type of the financial instrument (e.g., 'Instrument', 'Person')
          example: Instrument
        itemRank:
          type: integer
          format: int32
          description: Ranking position of the item in the watchlist
          default: 0
          example: 1
        itemAddedReason:
          type: string
          description: Reason the item was added to the watchlist
          example: Manual
        itemAddedDate:
          type: string
          format: date-time
          description: Date and time the item was added
        market:
          type: object
          description: Market metadata for the instrument when included
          properties:
            id:
              type: string
            symbolName:
              type: string
            displayName:
              type: string
            assetTypeId:
              type: integer
              format: int32
            assetTypeSubCategoryId:
              type: integer
              format: int32
              nullable: true
            exchangeId:
              type: integer
              format: int32
            hasExpirationDate:
              type: boolean
            avatar:
              type: object
              properties:
                small:
                  type: string
                medium:
                  type: string
                large:
                  type: string
                svg:
                  type: object
                  nullable: true
                  description: SVG avatar with background and text colors
                  properties:
                    url:
                      type: string
                    backgroundColor:
                      type: string
                    textColor:
                      type: string

````