API Documentation

Integrate AI-powered time series forecasting into your application.

Authentication

All API requests require an X-API-Key header. Find your API key on the Dashboard after subscribing.

X-API-Key: sk_your_api_key_here

Base URL

https://www.agentforecast.ai/api

POST `/tasks`

Submit a new forecasting task. Returns a task ID for tracking. Usage is metered on this endpoint only (counted on 201 response).

Request Body

Field	Type	Required	Description
payload	object	Yes	Forecast configuration and data
payload.parameters	array	Yes	Forecast parameters (e.g. forecasting_length)
parameter	string	Yes	Parameter name
value	any	Yes	Parameter value
payload.data	array	Yes	Time series datasets
dataset_type	string	Yes	`"feature"`
values	array	Yes	Array of `{"datetime", "value"}` objects

Common Parameters

Parameter	Type	Description
forecasting_length	integer	Duration to forecast ahead, in minutes. Output intervals match the time granularity of the input data.
latitude	float	Latitude for location-aware weather data
longitude	float	Longitude for location-aware weather data
region	string	Represented as an IANA timezone (e.g. `Europe/London`)
webhook_url	string	URL to receive a notification when the forecast completes

Example Request

POST /api/tasks

curl -X POST https://www.agentforecast.ai/api/tasks \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "parameters": [
        {"parameter": "forecasting_length", "value": 2880}
      ],
      "data": [
        {
          "dataset_type": "feature",
          "values": [
            {"datetime": "2026-03-07T00:00:00+00:00", "value": 142.5},
            {"datetime": "2026-03-08T00:00:00+00:00", "value": 135.2},
            {"datetime": "2026-03-09T00:00:00+00:00", "value": 147.8},
            {"datetime": "2026-03-10T00:00:00+00:00", "value": 130.1},
            {"datetime": "2026-03-11T00:00:00+00:00", "value": 132.0},
            {"datetime": "2026-03-12T00:00:00+00:00", "value": 125.8},
            {"datetime": "2026-03-13T00:00:00+00:00", "value": 138.9}
          ]
        }
      ]
    }
  }'

Response (201 Created)

{
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "pending"
  }
}

GET `/tasks/{task_id}`

Check the status of a forecast task. Poll this endpoint until status is done, or use a webhook.

Example Request

GET /api/tasks/{task_id}

curl https://www.agentforecast.ai/api/tasks/abc123-def456-ghi789 \
  -H "X-API-Key: sk_your_api_key"

Response (200 OK)

{
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "done"
  }
}

Task Statuses

pending processing done failed

GET `/tasks/{task_id}/result`

Retrieve the forecast results once the task status is done.

Example Request

GET /api/tasks/{task_id}/result

curl https://www.agentforecast.ai/api/tasks/abc123-def456-ghi789/result \
  -H "X-API-Key: sk_your_api_key"

Response (200 OK)

{
  "data": [
    {"datetime": "2026-03-14T00:00:00+00:00", "value": 118.4},
    {"datetime": "2026-03-15T00:00:00+00:00", "value": 124.4}
  ]
}

Errors

Status	Meaning	When
401	Unauthorised	Missing or invalid API key
403	Forbidden	Subscription not active
429	Too Many Requests	Monthly usage limit exceeded

What is MCP?

The Model Context Protocol (MCP) lets AI assistants like Claude and ChatGPT call AgentForecast as a native tool - no custom integration code needed. Once connected, your AI agent can submit forecasts, poll for completion, and retrieve results as part of any workflow.

The MCP endpoint uses Streamable HTTP (JSON-RPC 2.0 over HTTPS with optional Server-Sent Events). The same API key you use for the REST API authenticates MCP requests.

Connection

MCP Endpoint

https://www.agentforecast.ai/mcp

Authentication

Authorization: Bearer sk_your_api_key_here

Claude Desktop Setup

Add the following to your claude_desktop_config.json file:

claude_desktop_config.json

{
  "mcpServers": {
    "agentforecast": {
      "type": "http",
      "url": "https://www.agentforecast.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_api_key_here"
      }
    }
  }
}

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | %APPDATA%\Claude\claude_desktop_config.json (Windows)

OpenAI / ChatGPT Setup

AgentForecast works with the OpenAI Responses API and the OpenAI Agents SDK via remote MCP. Pass your API key in the Authorization header.

Responses API · gpt-4o, o3, etc.

Python

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_label": "agentforecast",
        "server_url": "https://www.agentforecast.ai/mcp",
        "headers": {
            "Authorization": "Bearer sk_your_api_key_here"
        },
        "require_approval": "never"
    }],
    input="Forecast the next 30 days of demand using my sales history."
)

OpenAI Agents SDK

Python — pip install openai-agents

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHTTP

mcp_server = MCPServerStreamableHTTP(
    url="https://www.agentforecast.ai/mcp",
    headers={"Authorization": "Bearer sk_your_api_key_here"}
)

agent = Agent(
    name="Forecasting Agent",
    instructions="Use AgentForecast to generate time series forecasts.",
    mcp_servers=[mcp_server]
)

result = await Runner.run(
    agent,
    "Forecast the next 30 days of demand using my sales history."
)

Available Tools

submit_forecast

Submit a time series forecasting job. Returns a task_id immediately. Usage is counted once per successful submission.

Parameters

Name	Type	Required	Description
data	array	Yes	Array of `{"datetime", "value"}` objects
forecasting_length	integer	Yes	How far to forecast ahead, in minutes
latitude	float	No	Latitude for weather features
longitude	float	No	Longitude for weather features
region	string	No	IANA timezone, e.g. `Europe/London`
webhook_url	string	No	URL notified when forecast completes

Example Tool Call

// What Claude sends to the MCP server
{
  "method": "tools/call",
  "params": {
    "name": "submit_forecast",
    "arguments": {
      "forecasting_length": 2880,
      "region": "Europe/London",
      "data": [
        {"datetime": "2026-03-07T00:00:00+00:00", "value": 142.5},
        {"datetime": "2026-03-08T00:00:00+00:00", "value": 135.2}
      ]
    }
  }
}

Response

Forecast submitted successfully.
task_id: abc123-def456-ghi789
status: pending

Call get_forecast_status(task_id='abc123-def456-ghi789') to poll for completion,
then get_forecast_result(task_id='abc123-def456-ghi789') once status is 'done'.

Usage: 3/150 forecasts this billing period.

get_forecast_status

Check the status of a submitted task. Poll until status is done.

Parameters

Name	Type	Required	Description
task_id	string	Yes	The task_id returned by submit_forecast

Statuses

pending processing done failed

get_forecast_result

Retrieve the forecasted values once status is done.

Parameters

Name	Type	Required	Description
task_id	string	Yes	The task_id returned by submit_forecast

Example Response

[
  {"datetime": "2026-03-14T00:00:00+00:00", "value": 118.4},
  {"datetime": "2026-03-15T00:00:00+00:00", "value": 124.4},
  ...
]

Typical Workflow

1 Call submit_forecast with your historical data and forecasting length. Receive a task_id.
2 Call get_forecast_status periodically until it returns done. Typically completes within 30-120 seconds.
3 Call get_forecast_result to retrieve the forecasted values as a datetime/value array.

Errors

Tool errors are returned as MCP tool results with isError: true and a plain-text description. HTTP-level errors follow standard JSON-RPC 2.0 error codes.

Condition	Behaviour
Missing / invalid API key	HTTP 401, JSON-RPC error code `-32001`
Subscription not active	HTTP 403, JSON-RPC error code `-32001`
Usage limit exceeded	Tool result with `isError: true` and upgrade link
Task not found	Tool result with `isError: true`

Support

Need help? Contact us at support@agentforecast.ai

API Documentation

Authentication

Base URL

POST /tasks

Request Body

Common Parameters

Example Request

Response (201 Created)

GET /tasks/{task_id}

Example Request

Response (200 OK)

Task Statuses

GET /tasks/{task_id}/result

Example Request

Response (200 OK)

Errors

What is MCP?

Connection

Claude Desktop Setup

OpenAI / ChatGPT Setup

Available Tools

submit_forecast

Parameters

Example Tool Call

Response

get_forecast_status

Parameters

Statuses

get_forecast_result

Parameters

Example Response

Typical Workflow

Errors

Support

POST `/tasks`

GET `/tasks/{task_id}`

GET `/tasks/{task_id}/result`