Put/Call Data API

Retrieve options market data including put/call ratios, volume, and price. Track options positioning and sentiment.

Endpoint

GET /v2/put-call-ratio/{symbol}

Authentication

Authenticate using one of the following methods (in order of recommendation):

Method	Example
Bearer token (recommended)	Authorization: Bearer YOUR_API_KEY
X-API-Key header	X-API-Key: YOUR_API_KEY
Query parameter	?apiKey=YOUR_API_KEY
Legacy query parameter	?token=YOUR_API_KEY

Parameters

Path Parameters

Parameter	Type	Required	Description
symbol	string	Yes	Stock ticker symbol (e.g., AAPL, MSFT)

Query Parameters

Parameter	Type	Required	Description
startDate	string	No	Start date (YYYY-MM-DD)
endDate	string	No	End date (YYYY-MM-DD)
limit	integer	No	Maximum number of results to return

Request

Python SDK

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

df = fb.options.put_call("AAPL",
                         date_from="2025-01-01",
                         date_to="2025-06-30",
                         as_dataframe=True)
print(df)

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.finbrain.tech/v2/put-call-ratio/AAPL"

Python (requests)

import requests

url = "https://api.finbrain.tech/v2/put-call-ratio/AAPL"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"startDate": "2026-01-01", "endDate": "2026-01-31"}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for pc in data["data"]["data"]:
    print(f"{pc['date']}: ratio {pc['ratio']:.2f} "
          f"(calls: {pc['callVolume']}, puts: {pc['putVolume']}, "
          f"total: {pc['totalVolume']}, price: {pc['price']})")

C++

#include <iostream>
#include <string>
#include <curl/curl.h>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

size_t WriteCallback(void* contents, size_t size, size_t nmemb, std::string* userp) {
    userp->append((char*)contents, size * nmemb);
    return size * nmemb;
}

json get_put_call_data(const std::string& symbol, const std::string& api_key) {
    CURL* curl = curl_easy_init();
    std::string response;

    if (curl) {
        std::string url = "https://api.finbrain.tech/v2/put-call-ratio/" + symbol;

        struct curl_slist* headers = nullptr;
        std::string auth_header = "Authorization: Bearer " + api_key;
        headers = curl_slist_append(headers, auth_header.c_str());

        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);
        curl_easy_perform(curl);
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }

    return json::parse(response);
}

int main() {
    auto result = get_put_call_data("AAPL", "YOUR_API_KEY");

    for (auto& pc : result["data"]["data"]) {
        std::cout << pc["date"].get<std::string>() << ": ratio "
                  << pc["ratio"].get<double>()
                  << " (calls: " << pc["callVolume"].get<int64_t>()
                  << ", puts: " << pc["putVolume"].get<int64_t>()
                  << ", total: " << pc["totalVolume"].get<int64_t>()
                  << ", price: " << pc["price"].get<double>() << ")"
                  << std::endl;
    }

    return 0;
}

Rust

use reqwest::blocking::Client;
use serde::Deserialize;
use std::error::Error;

#[derive(Debug, Deserialize)]
struct PutCallEntry {
    date: String,
    ratio: f64,
    #[serde(rename = "callVolume")]
    call_volume: i64,
    #[serde(rename = "putVolume")]
    put_volume: i64,
    #[serde(rename = "totalVolume")]
    total_volume: i64,
    price: f64,
}

#[derive(Debug, Deserialize)]
struct PutCallData {
    symbol: String,
    name: String,
    data: Vec<PutCallEntry>,
}

#[derive(Debug, Deserialize)]
struct Meta {
    timestamp: String,
}

#[derive(Debug, Deserialize)]
struct PutCallResponse {
    success: bool,
    data: PutCallData,
    meta: Meta,
}

fn get_put_call_data(symbol: &str, api_key: &str)
    -> Result<PutCallResponse, Box<dyn Error>> {
    let url = format!(
        "https://api.finbrain.tech/v2/put-call-ratio/{}",
        symbol
    );

    let client = Client::new();
    let response: PutCallResponse = client
        .get(&url)
        .bearer_auth(api_key)
        .send()?
        .json()?;

    Ok(response)
}

fn main() -> Result<(), Box<dyn Error>> {
    let result = get_put_call_data("AAPL", "YOUR_API_KEY")?;

    for pc in &result.data.data {
        println!("{}: ratio {:.2} (calls: {}, puts: {}, total: {}, price: {:.2})",
            pc.date, pc.ratio, pc.call_volume, pc.put_volume,
            pc.total_volume, pc.price);
    }

    Ok(())
}

JavaScript

const response = await fetch(
  "https://api.finbrain.tech/v2/put-call-ratio/AAPL",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const { data } = await response.json();

data.data.forEach(pc => {
  console.log(`${pc.date}: ratio ${pc.ratio} (calls: ${pc.callVolume}, puts: ${pc.putVolume}, total: ${pc.totalVolume}, price: ${pc.price})`);
});

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "data": [
      {
        "date": "2026-01-19",
        "ratio": 0.5,
        "callVolume": 620689,
        "putVolume": 310344,
        "totalVolume": 931034,
        "price": 255.53
      },
      {
        "date": "2026-01-16",
        "ratio": 1.42,
        "callVolume": 442233,
        "putVolume": 627971,
        "totalVolume": 1070205,
        "price": 258.21
      }
    ]
  },
  "meta": { "timestamp": "2026-01-19T15:06:21.343Z" }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data.symbol	string	Stock ticker symbol
data.name	string	Company name
data.data	array	Array of put/call data points
meta.timestamp	string	Response timestamp (ISO 8601)

Put/Call Object Fields

Field	Type	Description
date	string	Date (YYYY-MM-DD)
ratio	number	Put/call ratio
callVolume	integer	Call options volume
putVolume	integer	Put options volume
totalVolume	integer	Total options volume (calls + puts)
price	number	Closing price on this date

Interpretation

Ratio	Interpretation
Above 1.2	Heavy put activity (bearish/hedging)
0.7 - 1.2	Normal range
Below 0.7	Heavy call activity (bullish)

Errors

Code	Error	Description
400	Bad Request	Invalid symbol or parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Authenticated, but not authorized to access this resource
404	Not Found	Symbol not found
429	Too Many Requests	Rate limit exceeded — wait and retry
500	Internal Server Error	Server-side error

Related

• Put/Call Ratio Dataset - Use cases and analysis examples
• Sentiments - News sentiment
• Analyst Ratings - Wall Street ratings
• Ticker Predictions - AI predictions