Foretelle API

Integrate powerful AI-driven forecasting capabilities directly into your applications with our comprehensive REST API and developer tools.

Powerful Forecasting for Developers

Seamlessly integrate Foretelle's advanced forecasting with your existing systems

🚀

Easy Integration

RESTful API design with comprehensive documentation, SDKs, and code examples to get your integration up and running quickly.

⚙️

Flexible Models

Multiple forecasting models optimized for different use cases, data patterns, and time horizons.

📊

Rich Responses

Comprehensive results including forecast values, confidence intervals, driving factors, and natural language explanations.

⚡

High Performance

Optimized for fast response times with global edge deployment and robust caching strategies.

🔐

Enterprise Security

Industry-leading security with TLS encryption, API key authentication, and optional custom security configurations.

📱

Multi-platform

Official SDKs available for JavaScript, Python, Java, Ruby, PHP, and more with excellent community support.

Getting Started

Follow these simple steps to start integrating Foretelle in your application

Create an account

Generate API Key

Create an API key from your dashboard and configure access permissions based on your needs.

Example API Key:

ft_live_WsRSHD8smVYujbH9tnxHwqza7KtNJcgLMfP6kXZ2

Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, or in your application.

Choose Your Integration Method

Decide whether to use our RESTful API directly or integrate with one of our client libraries for your preferred language.

JavaScript

Node.js and browser compatible

Get SDK

Python

Python 3.6+ compatible

Get SDK

Java

Java 8+ compatible

Get SDK

Make Your First API Call

Start with a simple request to verify your integration is working correctly.

curl -X POST https://api.foretelle.com/v1/forecasts \
  -H "Authorization: Bearer ft_live_WsRSHD8smVYujbH9tnxHwqza7KtNJcgLMfP6kXZ2" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"date": "2024-01-01", "value": 120},
      {"date": "2024-02-01", "value": 135},
      {"date": "2024-03-01", "value": 142},
      {"date": "2024-04-01", "value": 156},
      {"date": "2024-05-01", "value": 170}
    ],
    "forecast_horizon": 3,
    "confidence_level": 0.95,
    "include_explanation": true
  }'

API Reference

Comprehensive documentation for all available endpoints

POST/v1/forecasts

Generate forecasts based on historical time series data with optional configurations for model type, horizons, and confidence intervals.

Request Parameters

Parameter	Type	Required	Description
data	Array	Yes	Array of objects with date and value properties representing historical data points
forecast_horizon	Integer	Yes	Number of periods to forecast into the future
confidence_level	Float	No	Confidence level for prediction intervals (0.0-1.0, default: 0.95)
model_type	String	No	Forecasting model to use (options: "auto", "arima", "prophet", "neural", default: "auto")
include_explanation	Boolean	No	Whether to include natural language explanation of forecast (default: false)

Request Example

{
  "data": [
    {"date": "2024-01-01", "value": 120},
    {"date": "2024-02-01", "value": 135},
    {"date": "2024-03-01", "value": 142},
    {"date": "2024-04-01", "value": 156},
    {"date": "2024-05-01", "value": 170}
  ],
  "forecast_horizon": 3,
  "confidence_level": 0.95,
  "model_type": "auto",
  "include_explanation": true
}

Response Example

{
  "success": true,
  "request_id": "req_7a9b8c7d6e5f4a3b2c1d",
  "forecast": {
    "values": [
      {"date": "2024-06-01", "value": 184.2},
      {"date": "2024-07-01", "value": 197.8},
      {"date": "2024-08-01", "value": 210.3}
    ],
    "confidence_intervals": [
      {
        "date": "2024-06-01",
        "lower": 172.6,
        "upper": 195.8
      },
      {
        "date": "2024-07-01",
        "lower": 182.3,
        "upper": 213.4
      },
      {
        "date": "2024-08-01",
        "lower": 190.1,
        "upper": 230.5
      }
    ],
    "model_used": "prophet",
    "accuracy_metrics": {
      "mape": 2.8,
      "rmse": 4.2
    },
    "driving_factors": [
      {
        "name": "trend",
        "contribution": 0.75,
        "description": "Upward linear trend"
      },
      {
        "name": "seasonality",
        "contribution": 0.25,
        "description": "Monthly pattern detected"
      }
    ],
    "explanation": "This forecast shows a strong upward trend with approximately 7.2% growth per month. The trend accounts for 75% of the predicted increase, while seasonal patterns contribute the remaining 25%. Based on historical data patterns, we predict continued strong growth through August with high confidence (95% confidence interval)."
  }
}

POST/v1/forecast-scenarios

Generate multiple forecast scenarios based on different assumptions and parameters.

Request Parameters

Parameter	Type	Required	Description
data	Array	Yes	Array of objects with date and value properties representing historical data points
forecast_horizon	Integer	Yes	Number of periods to forecast into the future
scenarios	Object	Yes	Configuration for different scenarios (base, optimistic, pessimistic)
include_explanation	Boolean	No	Whether to include natural language explanation for each scenario (default: false)

Request Example

{
  "data": [
    {"date": "2024-01-01", "value": 120},
    {"date": "2024-02-01", "value": 135},
    {"date": "2024-03-01", "value": 142},
    {"date": "2024-04-01", "value": 156},
    {"date": "2024-05-01", "value": 170}
  ],
  "forecast_horizon": 3,
  "scenarios": {
    "base": { "growth_adjustment": 1.0 },
    "optimistic": { "growth_adjustment": 1.2 },
    "pessimistic": { "growth_adjustment": 0.8 }
  },
  "include_explanation": true
}

POST/v1/multivariate-forecast

Generate forecasts incorporating multiple data variables and external factors.

Request Parameters

Parameter	Type	Required	Description
target_variable	Object	Yes	Configuration and historical data for the target variable to forecast
explanatory_variables	Array	Yes	Array of variables that may influence the target variable
forecast_horizon	Integer	Yes	Number of periods to forecast into the future
advanced_options	Object	No	Additional configuration options for the multivariate model

GET/v1/forecasts/{forecast_id}

Retrieve a previously generated forecast by its ID.

Request Parameters

Parameter	Type	Required	Description
forecast_id	String	Yes	Unique identifier for the forecast

GET/v1/models

List all available forecasting models and their capabilities.

POST/v1/model-evaluation

Evaluate different forecasting models on your data to determine the best fit.

Request Parameters

Parameter	Type	Required	Description
data	Array	Yes	Array of objects with date and value properties representing historical data points
models_to_evaluate	Array	No	Array of model types to evaluate (default: evaluates all available models)
evaluation_method	String	No	Method to use for evaluation (options: "holdout", "cross-validation", default: "holdout")

POST/v1/anomaly-detection

Detect anomalies and outliers in historical time series data.

Request Parameters

Parameter	Type	Required	Description
data	Array	Yes	Array of objects with date and value properties representing historical data points
sensitivity	Float	No	Threshold for anomaly detection (0.0-1.0, default: 0.95)
include_explanation	Boolean	No	Whether to include natural language explanation for detected anomalies (default: false)

Ready to Transform Your Forecasting?

Start integrating Foretelle's powerful AI forecasting capabilities into your applications today.

Create Your API Key