List watchlists

Written and maintained by The ProspectAPIs team

GET/v1/watchlists

GET /v1/watchlists is the ProspectAPIs operation listWatchlists, in the Watchlists group of the REST API. This account's watchlists, newest first, without their signing secrets. Free. Cost: free. Send your API key as a Bearer token in the Authorization header.

How this fits with the rest of the watchlists API, with worked examples, is in the watchlists guide.

Parameters

This operation takes no path or query parameters.

Responses

Response codes of GET /v1/watchlists
Status	Meaning
200	The account's watchlists.
401	The API key is missing or invalid.
429	Too many requests; retry after the window.

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

200 response fields

The account's watchlists.

Fields of the 200 response
Field	Type	Description
data required	array of Watchlist
data[].id required	string (uuid)
data[].name required	string
data[].filters required	WatchlistFilters	The GET /v1/funding filters a watchlist may hold (date windows and paging belong to the API call, not to an alert). At least one is required. Values may be strings or numbers.
data[].webhook_url required	string (uri)
data[].active required	boolean
data[].paused_reason	string or null	Why it was paused, if it was (revoked key, repeated webhook failures, filters no longer valid).
data[].created_at required	string (date-time)

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl

curl https://api.prospectapis.com/v1/watchlists \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY"

JavaScript (fetch)

const res = await fetch("https://api.prospectapis.com/v1/watchlists", {
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

Python (requests)

import os, requests

res = requests.get(
    "https://api.prospectapis.com/v1/watchlists",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

This call is free: it never spends credits or free records, so you can call it as often as the rate limit allows. Metered calls on the same key report your balance after each response in X-Credits-Remaining, and GET /v1/account shows it at any time.

The watchlists guide covers this area end to end. Previous operation: Poll a research brief. Next operation: Create a watchlist. Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values.

Was this page helpful?