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.

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