API Guide

Everything you need to integrate the Cotrader Screener API into your applications.

1. Authentication

All API requests require an API key. Pass it in the X-API-Key header.

curl -H "X-API-Key: ct_live_your_key_here" \
  https://api.Cotrader.com/api/screener/screen

Important: Your API key is shown only once when created. Store it securely. If lost, revoke it and create a new one from the API Keys page.

2. Quick Start

Screen stocks with a single API call using plain English:

Request

curl -X POST https://api.Cotrader.com/api/screener/screen \
  -H "X-API-Key: ct_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"naturalLanguageQuery": "RSI below 30 and price above 200 SMA"}'

Response 200 OK

{
  "success": true,
  "matchCount": 12,
  "totalStocksScanned": 11247,
  "interpretedAs": "RSI(14) < 30 AND Close > SMA(200)",
  "matches": [
    {
      "symbol": "INTC",
      "name": "Intel Corp",
      "sector": "Technology",
      "indicators": {
        "rsi:14": 24.3,
        "sma:200": 28.15,
        "close": 29.42
      }
    },
    ...
  ]
}

3. API Endpoints

POST /api/screener/screen

Execute a stock screen from a natural language query. This is the primary endpoint.

Request body:

{
  "naturalLanguageQuery": "string (required)",
  "maxResults": 100,           // 1-500, default 100
  "includePartialDay": false,  // use intraday data if available
  "asOfDate": null             // screen as of a specific date (YYYY-MM-DD)
}

GET /api/keys/usage

Check your current rate limit usage, daily screen count, and tier limits.

4. Screening Queries

Write your criteria in plain English. The AI understands natural language and converts it to structured screening rules. Cotrader supports 35+ technical indicators including moving averages, RSI, MACD, ATR, and price changes, plus 20+ fundamental metrics like P/E, EPS, dividend yield, ROE, and more.

View the full Screening Guide — indicators, examples, and tips

5. Saved Screens

Save frequently-used queries as screens. Saved screens cache the compiled rules so re-execution is faster and doesn't require re-compilation.

POST /api/screens

Create a saved screen. Compiles and caches the query.

{ "name": "Oversold Bounces", "naturalLanguageQuery": "RSI below 30 and price above 200 SMA" }

POST /api/screens/{id}/execute

Execute a saved screen using cached rules. Faster than re-screening from scratch.

GET /api/screens

List your saved screens with pagination.

PUT /api/screens/{id} | DELETE /api/screens/{id}

Update or delete a saved screen.

6. Rate Limits

Daily screen quotas depend on your subscription tier. All tiers share a burst limit of 30 requests/min.

Tier	Screens/Day	Price
Free	10	$0/mo
Starter	50	$19/mo
Pro	200	$49/mo
Unlimited	Unlimited	$149/mo

Daily quotas reset at midnight UTC. When a rate limit is hit, the API returns 429 Too Many Requests with a Retry-After header.

7. Error Handling

Status	Meaning
200	Success
400	Invalid query or request body. Check the `error` field.
401	Missing or invalid API key
404	Resource not found (screen or symbol)
429	Rate limit exceeded. Check `Retry-After` header.

Screening errors return 200 with "success": false and an error message explaining what went wrong.

Ready to start building?

Get an API Key View Pricing