Price Forecasts API

Retrieve price forecasts for a specific ticker. Returns daily or monthly forecasts with directional signals and confidence bounds, generated from ARIMA time-series models.

Endpoint

GET /v2/predictions/{type}/{symbol}

Authentication

Supports multiple authentication methods (in order of preference):

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
type	string	Yes	Prediction type: daily or monthly
symbol	string	Yes	Stock ticker symbol (e.g., AAPL, MSFT)

Query Parameters

Parameter	Type	Required	Description
apiKey	string	No	Your API key (if not using header auth)

Note: Predictions are forward-looking only. The API returns forecasts from the current date forward (10 days for daily, 12 months for monthly). Historical predictions are not available.

Request

Python SDK

from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_API_KEY")

# Get daily predictions
df = fb.predictions.ticker("AAPL", prediction_type="daily",
                           as_dataframe=True)
print(df)

# Get monthly predictions
df = fb.predictions.ticker("AAPL", prediction_type="monthly",
                           as_dataframe=True)
print(df)

cURL

# Get daily predictions (10 days forward)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.finbrain.tech/v2/predictions/daily/AAPL"

# Get monthly predictions (12 months forward)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.finbrain.tech/v2/predictions/monthly/AAPL"

Python (requests)

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Get daily predictions
response = requests.get(
    "https://api.finbrain.tech/v2/predictions/daily/AAPL",
    headers=headers
)
data = response.json()

# Get monthly predictions
response = requests.get(
    "https://api.finbrain.tech/v2/predictions/monthly/AAPL",
    headers=headers
)
data = response.json()

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_predictions(const std::string& symbol, const std::string& type,
                     const std::string& api_key) {
    CURL* curl = curl_easy_init();
    std::string response;

    if (curl) {
        std::string url = "https://api.finbrain.tech/v2/predictions/" + type +
                          "/" + 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_predictions("AAPL", "daily", "YOUR_API_KEY");
    auto data = result["data"];
    auto metadata = data["metadata"];

    std::cout << "Symbol: " << data["symbol"].get<std::string>() << std::endl;
    std::cout << "Expected Short-term: " << metadata["expectedShortTerm"].get<double>() << "%" << std::endl;
    std::cout << "Expected Mid-term: " << metadata["expectedMidTerm"].get<double>() << "%" << std::endl;
    std::cout << "Expected Long-term: " << metadata["expectedLongTerm"].get<double>() << "%" << std::endl;

    // Iterate over predictions array
    for (auto& pred : data["predictions"]) {
        std::cout << pred["date"].get<std::string>() << ": $"
                  << pred["mid"].get<double>()
                  << " (" << pred["lower"].get<double>()
                  << " - " << pred["upper"].get<double>() << ")" << std::endl;
    }

    return 0;
}

Rust

use reqwest::blocking::Client;
use reqwest::header::{AUTHORIZATION, HeaderValue};
use serde::Deserialize;
use std::error::Error;

#[derive(Debug, Deserialize)]
struct ApiResponse {
    success: bool,
    data: PredictionData,
}

#[derive(Debug, Deserialize)]
struct PredictionData {
    symbol: String,
    name: String,
    #[serde(rename = "type")]
    pred_type: String,
    predictions: Vec<Prediction>,
    metadata: Metadata,
    #[serde(rename = "lastUpdated")]
    last_updated: String,
}

#[derive(Debug, Deserialize)]
struct Prediction {
    date: String,
    mid: f64,
    lower: f64,
    upper: f64,
}

#[derive(Debug, Deserialize)]
struct Metadata {
    #[serde(rename = "expectedShortTerm")]
    expected_short_term: f64,
    #[serde(rename = "expectedMidTerm")]
    expected_mid_term: f64,
    #[serde(rename = "expectedLongTerm")]
    expected_long_term: f64,
    #[serde(rename = "lowerBoundChange")]
    lower_bound_change: f64,
    #[serde(rename = "upperBoundChange")]
    upper_bound_change: f64,
}

fn get_predictions(symbol: &str, pred_type: &str, api_key: &str)
    -> Result<ApiResponse, Box<dyn Error>> {
    let url = format!(
        "https://api.finbrain.tech/v2/predictions/{}/{}",
        pred_type, symbol
    );

    let client = Client::new();
    let response: ApiResponse = client
        .get(&url)
        .header(AUTHORIZATION, HeaderValue::from_str(&format!("Bearer {}", api_key))?)
        .send()?
        .json()?;

    Ok(response)
}

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

    println!("Symbol: {} ({})", data.symbol, data.name);
    println!("Expected Short-term: {}%", data.metadata.expected_short_term);
    println!("Expected Long-term: {}%", data.metadata.expected_long_term);

    for pred in &data.predictions {
        println!("{}: ${:.2} (${:.2} - ${:.2})", pred.date, pred.mid, pred.lower, pred.upper);
    }

    Ok(())
}

JavaScript

const response = await fetch(
  "https://api.finbrain.tech/v2/predictions/daily/AAPL",
  {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  }
);
const result = await response.json();
console.log(result.data);

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "type": "daily",
    "predictions": [
      { "date": "2026-01-16", "mid": 255.21, "lower": 251.01, "upper": 259.48 },
      { "date": "2026-01-20", "mid": 255.59, "lower": 249.67, "upper": 261.66 },
      { "date": "2026-01-21", "mid": 255.97, "lower": 248.72, "upper": 263.43 },
      { "date": "2026-01-22", "mid": 256.35, "lower": 247.99, "upper": 265.00 },
      { "date": "2026-01-23", "mid": 256.74, "lower": 247.39, "upper": 266.44 }
    ],
    "metadata": {
      "expectedShortTerm": 0.17,
      "expectedMidTerm": 0.47,
      "expectedLongTerm": 1.22,
      "lowerBoundChange": -3.95,
      "upperBoundChange": 6.67
    },
    "lastUpdated": "2026-01-19T15:05:59.853Z"
  },
  "meta": {
    "timestamp": "2026-01-19T15:05:59.853Z"
  }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request was successful
data	object	Prediction data object
meta	object	Response metadata

Data Object Fields

Field	Type	Description
symbol	string	Stock ticker symbol
name	string	Company name
type	string	Prediction type (daily or monthly)
predictions	array	Array of prediction objects
metadata	object	Expected move and bound change metrics
lastUpdated	string	When prediction was last updated (ISO 8601)

Prediction Array Items

Each item in the predictions array contains:

Field	Type	Description
date	string	Forecast date (YYYY-MM-DD)
mid	number	The model’s mid-point price forecast
lower	number	Lower confidence bound
upper	number	Upper confidence bound

Metadata Object Fields

Field	Type	Description
expectedShortTerm	number	Expected short-term price change % (~3 days)
expectedMidTerm	number	Expected mid-term price change % (~5 days)
expectedLongTerm	number	Expected long-term price change % (~10 days)
lowerBoundChange	number	Lower bound percentage change
upperBoundChange	number	Upper bound percentage change

Expected Move Interpretation

The expected move fields indicate percentage price change predictions:

Field	Time Horizon
expectedShortTerm	~3 trading days
expectedMidTerm	~5 trading days
expectedLongTerm	~10 trading days

Usage Examples

Basic Prediction Lookup

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://api.finbrain.tech/v2/predictions/daily/AAPL",
    headers=headers
)
result = response.json()
data = result["data"]
metadata = data["metadata"]

print(f"AAPL Prediction (updated {data['lastUpdated']})")
print(f"  Expected Short-term: {metadata['expectedShortTerm']}%")
print(f"  Expected Mid-term: {metadata['expectedMidTerm']}%")
print(f"  Expected Long-term: {metadata['expectedLongTerm']}%")

# Iterate over predictions array
for pred in data["predictions"]:
    print(f"  {pred['date']}: ${pred['mid']:.2f} (range: ${pred['lower']:.2f} - ${pred['upper']:.2f})")

Extract Price Forecasts

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

def get_price_forecasts(symbol):
    """Extract price forecasts from predictions"""
    response = requests.get(
        f"https://api.finbrain.tech/v2/predictions/daily/{symbol}",
        headers=headers
    )
    result = response.json()
    data = result["data"]

    for pred in data["predictions"]:
        print(f"{pred['date']}: ${pred['mid']:.2f} (${pred['lower']:.2f} - ${pred['upper']:.2f})")

    # Access bound change metrics
    metadata = data["metadata"]
    print(f"\nLower bound change: {metadata['lowerBoundChange']}%")
    print(f"Upper bound change: {metadata['upperBoundChange']}%")

get_price_forecasts("AAPL")

Analyze Multiple Tickers

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

tickers = ["AAPL", "MSFT", "GOOGL", "NVDA"]

for ticker in tickers:
    response = requests.get(
        f"https://api.finbrain.tech/v2/predictions/daily/{ticker}",
        headers=headers
    )
    result = response.json()
    metadata = result["data"]["metadata"]
    print(f"{ticker}: Short {metadata['expectedShortTerm']}%, Mid {metadata['expectedMidTerm']}%, Long {metadata['expectedLongTerm']}%")

Errors

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

Related

• Price Forecasts Dataset - Use cases and analysis examples
• Available Tickers - Check if a ticker has predictions
• News Sentiment - Get sentiment data for a ticker