Watchlists

Your stock lists; a stock strategy can run on one.

List your watchlists #

GET /v1/watchlists scope read

The caller's watchlists, by name: the same lists as the app's market watch.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

GET

curl "https://api.cirrus.trade/v1/watchlists" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://api.cirrus.trade/v1/watchlists",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://api.cirrus.trade/v1/watchlists', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": [
    {
      "id": "6adf47df14d372ca8aa51ea7",
      "name": "Breakouts",
      "count": 2,
      "updated_at": "2026-10-26T12:30:23.476Z"
    }
  ],
  "error": null
}

Create a watchlist #

POST /v1/watchlists scope watchlists

Creates a named watchlist of up to 50 NSE / BSE cash equities (instrument tokens).

More about this

At most 50 watchlists per user.

Body fields

name string required

Display name, 1-60 characters after trimming, unique per user; not one of the app's built-in lists (Indices, Nifty 50, Nifty Bank).
symbols string[] | null

Members as instrument tokens (instrument_token), at most 50, in order. Every symbol added must be an NSE or BSE cash equity in today's instrument list. On create, absent means empty; on update, absent keeps the members, present replaces them (members kept from before are not checked again).

Errors

HTTP	Code	When
400	malformed_json	The body is not JSON, or does not fit the request shape (unknown or missing fields, wrong types).
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	own_session_required	Credentials can only be created from the user's own signed-in session.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
409	watchlist_name_taken	The caller already has a watchlist with this name.
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

POST

curl -X POST "https://api.cirrus.trade/v1/watchlists" \
  -H "Authorization: token $CIRRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Breakouts",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }'

import os

import requests

response = requests.post(
    "https://api.cirrus.trade/v1/watchlists",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    json={
        "name": "Breakouts",
        "symbols": [
            "CT:EX:RELIANCE-EQ",
            "CT:EX:INFY-EQ",
        ],
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://api.cirrus.trade/v1/watchlists', {
  method: 'POST',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Breakouts",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }),
});
const body = await response.json();
console.log(response.status, body);

Response · 201

{
  "status": "success",
  "data": {
    "id": "6adf47df14d372ca8aa51ea4"
  },
  "error": null
}

Read a watchlist #

GET /v1/watchlists/{watchlist_id} scope read

A watchlist with each member's status today: tradable (a stock strategy on this list trades it), not_allowed (a cash equity automated strategies may not trade on this server), not_equity (an index or contract added from the market watch) or not_listed (not in today's instrument list).

Parameters

watchlist_id path · string required

Watchlist id.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	watchlist_not_found	No watchlist with this id for the caller.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

GET

curl "https://api.cirrus.trade/v1/watchlists/<watchlist_id>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://api.cirrus.trade/v1/watchlists/<watchlist_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://api.cirrus.trade/v1/watchlists/<watchlist_id>', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "id": "6adf47df14d372ca8aa51ea7",
    "name": "Breakouts",
    "symbols": [
      {
        "tradingsymbol": "RELIANCE-EQ",
        "stock": "RELIANCE",
        "exchange": "NSE",
        "name": "Reliance Industries",
        "status": "not_allowed",
        "instrument_token": "CT:EX:RELIANCE-EQ"
      },
      {
        "tradingsymbol": "INFY-EQ",
        "stock": "INFY",
        "exchange": "NSE",
        "name": "Infosys",
        "status": "not_allowed",
        "instrument_token": "CT:EX:INFY-EQ"
      }
    ],
    "tradable": 0,
    "updated_at": "2026-10-26T12:30:23.476Z"
  },
  "error": null
}

Rename a watchlist or replace its members #

PUT /v1/watchlists/{watchlist_id} scope watchlists

Sets the name and, when symbols is given, the members (kept members stay in place, new ones are added at the end).

More about this

Running stock strategies on this list pick the change up at their next entry: a stock taken out waits (watchlist_removed), its open trade keeps every exit. A list a running live strategy trades needs strategies_live on an API key or partner token too (403 live_not_enabled).

Parameters

watchlist_id path · string required

Watchlist id.

Body fields

name string required

Display name, 1-60 characters after trimming, unique per user; not one of the app's built-in lists (Indices, Nifty 50, Nifty Bank).
symbols string[] | null

Members as instrument tokens (instrument_token), at most 50, in order. Every symbol added must be an NSE or BSE cash equity in today's instrument list. On create, absent means empty; on update, absent keeps the members, present replaces them (members kept from before are not checked again).

Errors

HTTP	Code	When
400	malformed_json	The body is not JSON, or does not fit the request shape (unknown or missing fields, wrong types).
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	own_session_required	Credentials can only be created from the user's own signed-in session.
403	live_not_enabled	Live deployments need the `strategies_live` scope and a broker open for live automated strategies.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	watchlist_not_found	No watchlist with this id for the caller.
409	watchlist_name_taken	The caller already has a watchlist with this name.
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

PUT

curl -X PUT "https://api.cirrus.trade/v1/watchlists/<watchlist_id>" \
  -H "Authorization: token $CIRRUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Breakouts (large caps)",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }'

import os

import requests

response = requests.put(
    "https://api.cirrus.trade/v1/watchlists/<watchlist_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    json={
        "name": "Breakouts (large caps)",
        "symbols": [
            "CT:EX:RELIANCE-EQ",
            "CT:EX:INFY-EQ",
        ],
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://api.cirrus.trade/v1/watchlists/<watchlist_id>', {
  method: 'PUT',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Breakouts (large caps)",
    "symbols": [
      "CT:EX:RELIANCE-EQ",
      "CT:EX:INFY-EQ"
    ]
  }),
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "id": "6adf47df14d372ca8aa51ea6"
  },
  "error": null
}

Delete a watchlist #

DELETE /v1/watchlists/{watchlist_id} scope watchlists

Deletes the watchlist, its members and notes.

More about this

Running stock strategies on it stop starting new trades (watchlist_deleted); open trades keep every exit. A list a running live strategy trades needs strategies_live on an API key or partner token too (403 live_not_enabled).

Parameters

watchlist_id path · string required

Watchlist id.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	own_session_required	Credentials can only be created from the user's own signed-in session.
403	live_not_enabled	Live deployments need the `strategies_live` scope and a broker open for live automated strategies.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	watchlist_not_found	No watchlist with this id for the caller.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

DELETE

curl -X DELETE "https://api.cirrus.trade/v1/watchlists/<watchlist_id>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.delete(
    "https://api.cirrus.trade/v1/watchlists/<watchlist_id>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://api.cirrus.trade/v1/watchlists/<watchlist_id>', {
  method: 'DELETE',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response: 204, no body.