Laplace API Documentation

Introduction

This comprehensive resource provides detailed insights and instructions for developers seeking to integrate and utilize the Laplace API. To get a quick overview of the API's capabilities, use the TRY IT OUT section for each endpoint below. Note that an API key is required to access and explore these features.

Authentication

The Laplace API utilizes a token-based authentication system for its API key. To obtain your API key and start using our services, please contact your Laplace Insights sales representative.

Include your API key in the request headers:

"Authorization": "YOUR_API_KEY"

Base URL: https://api.laplaceinsights.com

Steps to Consume an API

Follow these steps to effectively access and utilize the Laplace API, ensuring secure and efficient integration with your applications.

Select an HTTP client library (e.g., requests for Python)
Choose the appropriate API endpoint for your use case
Specify the required HTTP method (e.g., GET, POST)
Include all required parameters and headers, including your API key
Send the request to the designated API endpoint
Process and handle the API response appropriately

HTTP Status Codes

The Laplace API uses standard HTTP status codes to indicate the success or failure of an API request.

Code	Description
200	Success - The request was completed successfully.
400	Bad Request - Invalid parameters or malformed request.
401	Unauthorized - The request wasn't allowed or the API key was missing.
429	Too Many Requests - Rate limit exceeded.
500	Internal Server Error - Unexpected server error occurred.

Rate Limiting

The API implements rate limiting to ensure fair usage. Requests exceeding the limit will receive a 429 Too Many Requests status code.

Limit: 90 requests per minute

Applied Per: User or IP address

Scope: Per endpoint (each endpoint has its own rate limit)

ID Lookup & Notebooks

Access essential resources to help you work with the API. Use the ID Lookup tool to find the necessary identifiers for models and groups, and download example notebooks to quickly get started with working code samples.

API ID Lookup

Find IDs for alpha models, groups, and regime models

Lookup IDs →

Download Notebooks

Python notebooks with examples for all endpoints

Get Notebooks →

API Versioning

Our API uses URL-based versioning. When we make breaking changes, we release new versions (e.g., v2) which are indicated in the endpoint path. Non-breaking changes are added to existing endpoints.

Forecasts

Current Forecast - Tickers

POST

/v1/current-forecast/tickers/

This API endpoint provides the current forecast for assets relative to the S&P 500 (SPY), based on the specified forecast model and group.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Parameters

Parameter	Type	Description
forecast_model_id Required	integer	Forecast Model ID
tickers Required	array	Array of ticker symbols

Code Example (Python)

import requests

url = "https://api.laplaceinsights.com/v1/current-forecast/tickers/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

data = {
    'forecast_model_id': 4,
    'tickers': ['XLC', 'XLP', 'XLY']
}

response = requests.post(url, 
                          json=data, 
                          headers={'Authorization': API_KEY})

print(response.json())

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
benchmark	string	The benchmark ticker symbol used for comparison (e.g., SPY for S&P 500)
datetime	string	The date of the forecast in YYYY-MM-DD format
data	array	Array of forecast results for each requested ticker
ticker	string	The ticker symbol of the asset
score	float	The forecast score ranges from 0 to 1 and reflects the strength of the model's prediction.
prediction_side	string	Indicates whether the asset is predicted to perform "above" or "below" the benchmark

{
    "success": true,
    "status_code": 200,
    "benchmark": "SPY",
    "datetime": "2025-11-03",
    "data": [
        {
            "ticker": "XLC",
            "score": 0.48195770382881165,
            "prediction_side": "below"
        },
        {
            "ticker": "XLP",
            "score": 0.27617892622947693,
            "prediction_side": "below"
        },
        {
            "ticker": "XLY",
            "score": 0.37340497970581055,
            "prediction_side": "below"
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

API Key

Forecast Model ID

Tickers (comma-separated for UI; sent as array)

Current Forecast - Group

GET

/v1/current-forecast/group/

This API endpoint provides the current forecast for all assets in a specific watchlist group relative to the S&P 500 (SPY), based on the specified forecast model.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Parameters

Parameter	Type	Description
forecast_model_id Required	integer	Forecast Model ID
group_id Required	integer	Watchlist Group ID

Code Example (Python)

import requests

url = "https://api.laplaceinsights.com/v1/current-forecast/group/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

params = {
    'forecast_model_id': 4,
    'group_id': 110
}

response = requests.get(url, 
                          params=params, 
                          headers={'Authorization': API_KEY})

print(response.json())

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
benchmark	string	The benchmark ticker symbol used for comparison (e.g., SPY for S&P 500)
datetime	string	The date of the forecast in YYYY-MM-DD format
group_name	string	The name of the watchlist group
data	array	Array of forecast results for each ticker in the group
ticker	string	The ticker symbol of the asset
score	float	The forecast score ranges from 0 to 1 and reflects the strength of the model's prediction.
prediction_side	string	Indicates whether the asset is predicted to perform "above" or "below" the benchmark

{
    "success": true,
    "status_code": 200,
    "benchmark": "SPY",
    "datetime": "2025-11-03",
    "group_name": "Consumer Staples",
    "data": [
        {
            "ticker": "EL",
            "score": 0.2621215879917145,
            "prediction_side": "above"
        },
        {
            "ticker": "KMB",
            "score": 0.4610825181007385,
            "prediction_side": "below"
        },
        {
            "ticker": "CLX",
            "score": 0.49077147245407104,
            "prediction_side": "below"
        },
        {
            "ticker": "BG",
            "score": 0.44389820098876953,
            "prediction_side": "below"
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

API Key

Forecast Model ID

Group ID

Historical Forecast - Tickers

POST

/v1/historical-forecast/tickers/

This API endpoint allows you to retrieve historical forecasts for assets relative to the S&P 500 (SPY) based on specified forecast model, group, and date range.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Parameters

Parameter	Type	Description
forecast_model_id Required	integer	Forecast Model ID
tickers Required	array	Array of ticker symbols
start_date Required	string	Start date of forecast (YYYY-MM-DD)
end_date Required	string	End date of forecast (YYYY-MM-DD)
page Optional	integer	Page number for pagination (default is 1).

Code Example (Python)

import time
import requests

url = "https://api.laplaceinsights.com/v1/historical-forecast/tickers/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

data = {
    'forecast_model_id': 4,
    'tickers': ['AAPL', 'NVDA'],
    'start_date': '2005-01-01',
    'end_date': '2025-01-05',
}

all_data = []
page = 1

while True:
    # Add page number to data
    data['page'] = page
    
    # Make API request
    response = requests.post(url, 
                          json=data, 
                          headers={'Authorization': API_KEY})
    
    result = response.json()                  
    # Add current page data to all_data
    all_data.extend(result.get('data', []))
    
    # Check if there are more pages
    if not result.get('has_next'):
        break
        
    page += 1
    time.sleep(0.5)  # Small delay to avoid rate limiting

print(all_data)

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
page	integer	Current page number in the paginated results
total_pages	integer	Total number of pages available
has_next	boolean	Indicates whether there is a next page of results
has_previous	boolean	Indicates whether there is a previous page of results
benchmark	string	The benchmark ticker symbol used for comparison (e.g., SPY for S&P 500)
data	array	Array of historical forecast results for each ticker
ticker	string	The ticker symbol of the asset
datetime	array	Array of dates in YYYY-MM-DD format, ordered from most recent to oldest
score	array	Array of forecast scores corresponding to each datetime. The forecast score ranges from 0 to 1 and reflects the strength of the model's prediction.
prediction_side	array	Array of prediction sides corresponding to each datetime. Values are either "above" or "below" the benchmark

{
    "success": true,
    "status_code": 200,
    "page": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "benchmark": "SPY",
    "data": [
        {
            "ticker": "AAPL",
            "datetime": [
                "2025-01-03",
                "2025-01-02"
            ],
            "score": [
                0.45618337392807007,
                0.46378520131111145
            ],
            "prediction_side": [
                "above",
                "above"
            ]
        },
        {
            "ticker": "NVDA",
            "datetime": [
                "2025-01-03",
                "2025-01-02"
            ],
            "score": [
                0.514505922794342,
                0.3307415246963501
            ],
            "prediction_side": [
                "above",
                "below"
            ]
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

API Key

Forecast Model ID

Tickers (comma-separated for UI; sent as array)

Start Date

End Date

Page

Historical Forecast - Group

GET

/v1/historical-forecast/group/

This API endpoint allows you to retrieve historical forecasts for all assets in a specific watchlist group relative to the S&P 500 (SPY) based on specified forecast model, group ID, and date range.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Parameters

Parameter	Type	Description
forecast_model_id Required	integer	Forecast Model ID
group_id Required	integer	Watchlist Group ID
start_date Required	string	Start date of forecast (YYYY-MM-DD)
end_date Required	string	End date of forecast (YYYY-MM-DD)
page Optional	integer	Page number for pagination (default is 1).

Code Example (Python)

import time
import requests

url = "https://api.laplaceinsights.com/v1/historical-forecast/group/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

params = {
    'forecast_model_id': 4,
    'group_id': 110,
    'start_date': '2025-01-01',
    'end_date': '2025-01-05',
}

all_data = []
page = 1

while True:
    # Add page number to params
    params['page'] = page
    
    # Make API request
    response = requests.get(url, 
                          params=params, 
                          headers={'Authorization': API_KEY})
    
    result = response.json()                  
    # Add current page data to all_data
    all_data.extend(result.get('data', []))
    
    # Check if there are more pages
    if not result.get('has_next'):
        break
        
    page += 1
    time.sleep(0.5)  # Small delay to avoid rate limiting

print(all_data)

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
page	integer	Current page number in the paginated results
total_pages	integer	Total number of pages available
has_next	boolean	Indicates whether there is a next page of results
has_previous	boolean	Indicates whether there is a previous page of results
benchmark	string	The benchmark ticker symbol used for comparison (e.g., SPY for S&P 500)
group_name	string	The name of the watchlist group
data	array	Array of historical forecast results for each ticker in the group
ticker	string	The ticker symbol of the asset
datetime	array	Array of dates in YYYY-MM-DD format, ordered from most recent to oldest. May be empty if no data available for the ticker in the specified date range
score	array	Array of forecast scores corresponding to each datetime. The forecast score ranges from 0 to 1 and reflects the strength of the model's prediction.
prediction_side	array	Array of prediction sides corresponding to each datetime. Values are either "above" or "below" the benchmark. May be empty if no data available

{
    "success": true,
    "status_code": 200,
    "page": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "benchmark": "SPY",
    "group_name": "GICS - Consumer Staples",
    "data": [
        {
            "ticker": "EL",
            "datetime": [
                "2025-01-03",
                "2025-01-02"
            ],
            "score": [
                0.4589180052280426,
                0.43511962890625
            ],
            "prediction_side": [
                "below",
                "below"
            ]
        },
        {
            "ticker": "KMB",
            "datetime": [
                "2025-01-03",
                "2025-01-02"
            ],
            "score": [
                0.49546584486961365,
                0.49789169430732727
            ],
            "prediction_side": [
                "below",
                "below"
            ]
        },
        {
            "ticker": "KVUE",
            "datetime": [],
            "score": [],
            "prediction_side": []
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

API Key

Forecast Model ID

Group ID

Start Date

End Date

Page

Asset Regimes

Regime Models

GET

/v1/regime-models/

This API endpoint retrieves details of regime models, including the regime model ID, name, and the number of regimes.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Code Example (Python)

import requests

url = "https://api.laplaceinsights.com/v1/regime-models/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

response = requests.get(url, 
                          headers={'Authorization': API_KEY})

print(response.json())

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
total_count	integer	Total number of regime models available
data	array	Array of regime models with their details
regime_model_id	integer	Unique identifier for the regime model
name	string	Name of the regime model (e.g., "Responsive", "Persistent")
no_of_regimes	integer	Number of regimes in the model

{
    "success": true,
    "status_code": 200,
    "total_count": 2,
    "data": [
        {
            "regime_model_id": 231,
            "name": "Responsive",
            "no_of_regimes": 3
        },
        {
            "regime_model_id": 553,
            "name": "Persistent",
            "no_of_regimes": 3
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

Regime Model Assets

GET

/v1/regime-models/{model_id}/assets/

This API endpoint retrieves all assets associated with a specific Regime Model.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Parameters

Parameter	Type	Description
model_id Required	integer	The ID of the regime model (URL path parameter)

Code Example (Python)

import requests

MODEL_ID = 553
url = f"https://api.laplaceinsights.com/v1/regime-models/{MODEL_ID}/assets/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

response = requests.get(url, 
                          headers={'Authorization': API_KEY})

print(response.json())

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
total_count	integer	Total number of assets available for the specified regime model
data	array	Array of assets associated with the regime model
name	string	Full name of the asset or company
ticker	string	The ticker symbol of the asset

{
    "success": true,
    "status_code": 200,
    "total_count": 3129,
    "data": [
        {
            "name": "Cooper Companies",
            "ticker": "COO"
        },
        {
            "name": "ConocoPhillips",
            "ticker": "COP"
        },
        {
            "name": "GX Copper Miners ETF",
            "ticker": "COPX"
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

API Key

Model ID

Dominant Regime

GET

/v1/dominant-regime/

This API endpoint fetches the dominant regime for a given ticker and regime model over a specified date range.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Parameters

Parameter	Type	Description
regime_model_id Required	integer	The unique identifier for the regime model
ticker Required	string	The ticker symbol
start_date Required	string	The start date for the period over which the regime information is requested (YYYY-MM-DD)
end_date Required	string	The end date for the period over which the regime information is requested (YYYY-MM-DD)

Code Example (Python)

import requests

url = "https://api.laplaceinsights.com/v1/dominant-regime/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

params = {
    'regime_model_id': 231,
    'ticker': 'XLI',
    'start_date': '2025-01-01',
    'end_date': '2025-01-05',
}

response = requests.get(url, 
                          params=params, 
                          headers={'Authorization': API_KEY})

print(response.json())

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
total_count	integer	Total number of date records returned
ticker	string	The ticker symbol that was queried
data	array	Array of dominant regime assignments for each date
datetime	string	Date in YYYY-MM-DD format
regime	integer	The dominant regime number for the asset on that date (e.g., 1, 2, or 3)

{
    "success": true,
    "status_code": 200,
    "total_count": 2,
    "ticker": "XLI",
    "data": [
        {
            "datetime": "2025-01-02",
            "regime": 2
        },
        {
            "datetime": "2025-01-03",
            "regime": 2
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

API Key

Regime Model ID

Ticker

Start Date

End Date

Regime Metrics

POST

/v1/regime-metrics/

This API endpoint retrieves regime metrics for given tickers within a specified date range, providing the probability, mu, and sigma for each regime.

Headers

Header	Type	Description
Authorization Required	string	API Key for authentication

Parameters

Parameter	Type	Description
regime_model_id Required	integer	The unique identifier for the regime model
tickers Required	array	Array of ticker symbols
start_date Required	string	Start date for regime metrics (YYYY-MM-DD)
end_date Required	string	End date for regime metrics (YYYY-MM-DD)
page Optional	integer	Page number for pagination (default is 1)

Code Example (Python)

import time
import requests

url = "https://api.laplaceinsights.com/v1/regime-metrics/"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key
data = {
    'regime_model_id': 231,
    'tickers': ['AAPL'],
    'start_date': '2025-01-01',
    'end_date': '2025-01-05'
}

all_data = []
page = 1

while True:
    # Add page number to data
    data['page'] = page
    
    # Make API request
    response = requests.post(url, 
                          json=data, 
                          headers={'Authorization': API_KEY})
    
    result = response.json()                  
    # Add current page data to all_data
    all_data.extend(result.get('data', []))
    
    # Check if there are more pages
    if not result.get('has_next'):
        break
        
    page += 1
    time.sleep(0.5)  # Small delay to avoid rate limiting

print(all_data)

Response Examples

Attribute	Type	Description
success	boolean	Indicates whether the API request was successful
status_code	integer	HTTP status code of the response
page	integer	Current page number in the paginated results
total_pages	integer	Total number of pages available
has_next	boolean	Indicates whether there is a next page of results
has_previous	boolean	Indicates whether there is a previous page of results
data	array	Array of regime metrics for each ticker
ticker	string	The ticker symbol of the asset
dates	array	Array of date objects containing regime information
datetime	string	Date in YYYY-MM-DD format
regimes	array	Array of regime metrics for each regime on that date
regime	integer	Regime number identifier (e.g., 1, 2, or 3)
probability	float	Probability that the asset is in this regime (value between 0 and 1)
mu	float	Expected return (mean) for the asset when in this regime
sigma	float	Volatility (standard deviation) of returns for the asset when in this regime

{
    "success": true,
    "status_code": 200,
    "page": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "data": [
        {
            "ticker": "AAPL",
            "dates": [
                {
                    "datetime": "2025-01-03",
                    "regimes": [
                        {
                            "regime": 1,
                            "probability": 0.21568359434604645,
                            "mu": 0.19922369718551636,
                            "sigma": 0.9177297353744507
                        },
                        {
                            "regime": 2,
                            "probability": 0.7685746550559998,
                            "mu": 0.060604263097047806,
                            "sigma": 1.8748406171798706
                        },
                        {
                            "regime": 3,
                            "probability": 0.015741772949695587,
                            "mu": -0.3038657605648041,
                            "sigma": 3.638118028640747
                        }
                    ]
                },
                {
                    "datetime": "2025-01-02",
                    "regimes": [
                        {
                            "regime": 1,
                            "probability": 0.07120274752378464,
                            "mu": 0.19922369718551636,
                            "sigma": 0.9177297353744507
                        },
                        {
                            "regime": 2,
                            "probability": 0.9044011235237122,
                            "mu": 0.060604263097047806,
                            "sigma": 1.8748406171798706
                        },
                        {
                            "regime": 3,
                            "probability": 0.024396104738116264,
                            "mu": -0.3038657605648041,
                            "sigma": 3.638118028640747
                        }
                    ]
                }
            ]
        }
    ]
}

{
    "success": false,
    "error": {
        "status_code": "int",
        "message": "str",
        "detail": {}
    }
}

Try It Out

Note: For in-depth testing, it's best to use API clients or make requests directly from your code. Need model or group IDs ? Search ID →

API Key

Regime Model ID

Tickers (comma-separated for UI; sent as array)

Start Date

End Date

Page