API Documentation

Integrate AI-powered time series forecasting into your application with three simple endpoints.

Authentication

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

X-API-Key: sk_your_api_key_here

Base URL & Authentication

Sign up to get your API base URL and key.

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 Number of time steps to forecast (e.g. 43200 for 30 days of minute-level data)
latitude float Latitude for location-aware weather data
longitude float Longitude for location-aware weather data
timezone string 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": 43200}
      ],
      "data": [
        {
          "dataset_type": "feature",
          "values": [
            {"datetime": "2025-01-01T00:00:00Z", "value": 142.5},
            {"datetime": "2025-01-01T01:00:00Z", "value": 138.2},
            {"datetime": "2025-01-01T02:00:00Z", "value": 155.8}
          ]
        }
      ]
    }
  }'

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.

Path Parameters

Parameter Type Description
task_id string The task ID returned from POST /tasks

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.

Path Parameters

Parameter Type Description
task_id string The task ID returned from POST /tasks

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": "2025-02-01T00:00:00Z", "value": 148.3},
    {"datetime": "2025-02-01T01:00:00Z", "value": 152.1},
    {"datetime": "2025-02-01T02:00:00Z", "value": 145.7}
  ]
}

Errors

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

Support

Need help? Contact us at support@agentforecast.ai