> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nolano.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Request a Forecast
> Generate accurate time series predictions using Nolano's foundation models
Generate predictions for your time series data using state-of-the-art foundation models. This endpoint supports univariate forecasting with multiple model options optimized for different use cases.
**Processing Time**: Forecasts typically complete in 2-10 seconds depending on data size and model complexity.
## Available Models
Choose the best model for your forecasting needs. Each model is optimized for specific use cases and data characteristics:
| Model ID | Description | Best For |
| ------------------ | --------------------------------------- | ------------------------- |
| `forecast-model-1` | General-purpose foundation model (TOTO) | Most time series patterns |
| `forecast-model-2` | Trend-focused model | Data with strong trends |
| `forecast-model-3` | Seasonal model | Seasonal patterns |
| `forecast-model-4` | Volatility model | High-variance data |
For detailed model information and performance characteristics, see our [Supported Models](/models) page.
## Example Requests
```bash Daily Sales Forecast theme={null}
curl --location 'https://api.nolano.ai/forecast' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ak_your_api_key_here' \
--header 'X-Model-Id: forecast-model-1' \
--data '{
"series": [
{
"timestamps": [
"2023-01-01T00:00:00",
"2023-01-02T00:00:00",
"2023-01-03T00:00:00",
"2023-01-04T00:00:00",
"2023-01-05T00:00:00"
],
"values": [100, 102, 98, 105, 103]
}
],
"forecast_horizon": 7,
"data_frequency": "Daily",
"forecast_frequency": "Daily",
"confidence": 0.95
}'
```
```python Python with Pandas theme={null}
import requests
import pandas as pd
import json
# Sample time series data
data = {
'date': pd.date_range('2023-01-01', periods=30, freq='D'),
'sales': [100 + i * 2 + (i % 7) * 5 for i in range(30)]
}
df = pd.DataFrame(data)
request_payload = {
"series": [{
"timestamps": df['date'].dt.strftime('%Y-%m-%dT%H:%M:%S').tolist(),
"values": df['sales'].tolist()
}],
"forecast_horizon": 7,
"data_frequency": "Daily",
"forecast_frequency": "Daily",
"confidence": 0.95
}
response = requests.post(
"https://api.nolano.ai/forecast",
headers={
'Content-Type': 'application/json',
'Authorization': "Bearer ak_your_api_key_here",
'X-Model-Id': 'forecast-model-1'
},
json=request_payload
)
if response.status_code == 200:
forecast = response.json()
print("Forecast successful!")
print(f"Predicted values: {forecast['median']}")
else:
print(f"Error: {response.status_code}")
print(response.json())
```
```javascript Node.js theme={null}
const axios = require('axios');
const forecastData = {
series: [{
timestamps: [
"2023-01-01T00:00:00",
"2023-01-02T00:00:00",
"2023-01-03T00:00:00",
"2023-01-04T00:00:00",
"2023-01-05T00:00:00"
],
values: [100, 102, 98, 105, 103]
}],
forecast_horizon: 7,
data_frequency: "Daily",
forecast_frequency: "Daily",
confidence: 0.95
};
axios.post('https://api.nolano.ai/forecast', forecastData, {
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ak_your_api_key_here',
'X-Model-Id': 'forecast-model-1'
}
})
.then(response => {
console.log('Forecast successful!');
console.log('Predicted values:', response.data.median);
})
.catch(error => {
console.error('Error:', error.response?.data || error.message);
});
```
## Response Format
The API returns forecast data with prediction intervals:
```json Example Response theme={null}
{
"forecast_timestamps": [
"2024-01-01T00:00:00",
"2024-01-02T00:00:00",
"2024-01-03T00:00:00"
],
"lower_bound": [145.2, 146.8, 148.1],
"median": [150.0, 151.5, 153.2],
"upper_bound": [154.8, 156.2, 158.3]
}
```
## Data Requirements
* **Minimum data points**: 10 historical observations
* **Maximum forecast horizon**: 100 periods
* **Supported frequencies**: Seconds, Minutes, Hours, Daily, Weekly, Monthly, Quarterly, Yearly
* **Data format**: Chronologically ordered timestamps with corresponding numerical values
## Error Handling
The API returns structured error responses with specific error codes:
* `UNAUTHORIZED` - Invalid or missing API key
* `INVALID_REQUEST` - Validation failed for request parameters
* `DATA_VALIDATION_ERROR` - Issues with time series data format
* `RATE_LIMIT_EXCEEDED` - API rate limit exceeded
* `INTERNAL_ERROR` - Unexpected server error
Always check the HTTP status code and parse the error object for detailed information about failures.
## OpenAPI
````yaml POST /forecast
openapi: 3.1.0
info:
title: Nolano Time Series Forecasting API
description: >-
Enterprise-grade Time Series Foundation Models for forecasting and anomaly
detection with secure authentication, robust key management, and AWS-powered
reliability.
version: 1.0.0
contact:
name: Nolano Support
email: hello@nolano.com
url: https://nolano.ai
license:
name: Proprietary
url: https://nolano.ai/terms
servers:
- url: https://api.nolano.ai
description: Production API server
security:
- bearerAuth: []
tags:
- name: Authentication
description: API key verification and authentication
- name: Forecasting
description: Time series forecasting endpoints
paths:
/forecast:
post:
tags:
- Forecasting
summary: Request Time Series Forecast
description: Generate predictions for time series data using foundation models
operationId: requestForecast
parameters:
- name: X-Model-Id
in: header
description: Model ID to use for forecasting
required: false
schema:
type: string
enum:
- forecast-model-1
- forecast-model-2
- forecast-model-3
- forecast-model-4
default: forecast-model-1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ForecastRequest'
responses:
'200':
description: Forecast generated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ForecastResponse'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Data validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
ForecastRequest:
type: object
required:
- series
- forecast_horizon
- data_frequency
- forecast_frequency
properties:
series:
type: array
items:
$ref: '#/components/schemas/TimeSeries'
minItems: 1
maxItems: 1
description: Array containing one time series object
forecast_horizon:
type: integer
minimum: 1
maximum: 100
description: Number of future periods to predict
example: 12
data_frequency:
type: string
enum:
- Seconds
- Minutes
- Hours
- Daily
- Weekly
- Monthly
- Quarterly
- Yearly
description: Frequency of input timestamps
example: Daily
forecast_frequency:
type: string
enum:
- Seconds
- Minutes
- Hours
- Daily
- Weekly
- Monthly
- Quarterly
- Yearly
description: Desired frequency for forecast output (must match data_frequency)
example: Daily
confidence:
type: number
minimum: 0.1
maximum: 0.99
default: 0.95
description: Confidence level for prediction intervals
example: 0.95
ForecastResponse:
type: object
required:
- forecast_timestamps
- lower_bound
- median
- upper_bound
properties:
forecast_timestamps:
type: array
items:
type: string
format: date-time
description: Timestamps for forecasted periods
example:
- '2024-01-01T00:00:00'
- '2024-01-02T00:00:00'
lower_bound:
type: array
items:
type: number
format: float
description: Lower bounds of prediction intervals
example:
- 145.2
- 146.8
median:
type: array
items:
type: number
format: float
description: Point forecasts (median predictions)
example:
- 150
- 151.5
upper_bound:
type: array
items:
type: number
format: float
description: Upper bounds of prediction intervals
example:
- 154.8
- 156.2
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code
enum:
- UNAUTHORIZED
- INVALID_REQUEST
- DATA_VALIDATION_ERROR
- RATE_LIMIT_EXCEEDED
- INTERNAL_ERROR
example: INVALID_REQUEST
message:
type: string
description: Human-readable error message
example: Validation failed for one or more fields
details:
type: object
description: Additional error context and debugging information
additionalProperties: true
example:
field: forecast_horizon
issue: Must be between 1 and 100
provided: 150
TimeSeries:
type: object
required:
- timestamps
- values
properties:
timestamps:
type: array
items:
type: string
format: date-time
description: Array of timestamps in ISO 8601 format
minItems: 10
example:
- '2023-01-01T00:00:00'
- '2023-01-02T00:00:00'
- '2023-01-03T00:00:00'
values:
type: array
items:
type: number
format: float
description: Array of numerical values corresponding to timestamps
minItems: 10
example:
- 100.5
- 102.3
- 98.7
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: ak_[64_character_hex_string]
description: API key authentication. Include your API key with 'Bearer' prefix.
````