---
title: "Create a new watchlist"
method: POST
path: "/api/v1/watchlists"
tags: ["Watchlists"]
---

# Create a new watchlist

`POST /api/v1/watchlists`

**Rate limit:** 20 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:
- `DELETE /api/v1/watchlists/{watchlistId}`
- `DELETE /api/v1/watchlists/{watchlistId}/items`
- `POST /api/v1/watchlists/default-watchlist/selected-items`
- `POST /api/v1/watchlists/newasdefault-watchlist`
- `POST /api/v1/watchlists/{watchlistId}/items`
- `PUT /api/v1/watchlists/rank/{watchlistId}`
- `PUT /api/v1/watchlists/setUserSelectedUserDefault/{watchlistId}`
- `PUT /api/v1/watchlists/{watchlistId}`
- `PUT /api/v1/watchlists/{watchlistId}/items`

---

Creates a new watchlist for the authenticated user with the specified name and type.

## Query parameters

- `name` string, required
- `type` 'Static' | 'Dynamic'
- `dynamicQuery` string

## Headers

- `x-request-id` string, uuid, required
- `x-api-key` string, password, required
- `x-user-key` string, password, required

## Response `201`

Watchlist created successfully

- WatchlistsResponse — Response containing multiple watchlists with metadata
  - `status` integer — HTTP status code of the response
  - `watchlists` WatchlistResponse[] — List of user watchlists
    - `watchlistId` string — Unique identifier of the watchlist
    - `name` string — Display name of the watchlist
    - `Gcid` integer — Global Customer ID of the watchlist owner
    - `watchlistType` 'Static' | 'Dynamic' | 'RecentlyInvested' | 'Default' — Type of the watchlist
    - `totalItems` integer — Total number of items in the watchlist
    - `isDefault` boolean — Whether this is a default system watchlist
    - `isUserSelectedDefault` boolean — Whether this is the user's selected default watchlist
    - `watchlistRank` integer — Display order rank of the watchlist
    - `dynamicUrl` string, nullable — URL for dynamic watchlist queries
    - `items` WatchlistItemDto[] — Items contained in the watchlist
      - `itemId` integer, required — Unique identifier of the financial instrument
      - `itemType` string, required — Type of the financial instrument (e.g., 'Instrument', 'Person')
      - `itemRank` integer — Ranking position of the item in the watchlist
      - `itemAddedReason` string — Reason the item was added to the watchlist
      - `itemAddedDate` string, date-time — Date and time the item was added
      - `market` object — Market metadata for the instrument when included
        - `id` string
        - `symbolName` string
        - `displayName` string
        - `assetTypeId` integer
        - `assetTypeSubCategoryId` integer, nullable
        - `exchangeId` integer
        - `hasExpirationDate` boolean
        - `avatar` object
          - `small` string
          - `medium` string
          - `large` string
          - `svg` object, nullable — SVG avatar with background and text colors
            - `url` string
            - `backgroundColor` string
            - `textColor` string
    - `relatedAssets` integer[], nullable — Related asset IDs
  - `exception` object — Exception details when the request partially failed
    - `invalidItems` string[] — List of invalid item identifiers
    - `reason` string — Reason for the exception
    - `message` string — Human-readable exception message
  - `meta` object — Response metadata including pagination info
    - `pageNumber` integer — Current page number
    - `itemsPerPage` integer — Number of items per page
    - `maxItemsInWatchlistLimit` integer — Maximum allowed items per watchlist
    - `maxWatchlistsLimit` integer — Maximum allowed watchlists per user
  - `isSucceeded` boolean — Whether the request succeeded

## Other responses

- `429` — Too Many Requests — the shared rate limit (20 requests / 60s) was exceeded.

---

[API](https://skmtc.net/etoro/apis/etoro-api.md) · [All operations](https://skmtc.net/etoro/apis/etoro-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/etoro/etoro-api/versions/69c1fb266c35/schema)