TimesFM API Integration

This document explains how to consume the prediction API from another project.

It does not include infrastructure details, private data, or internal deployment specs. It only details request/response contracts, authentication, and integration examples.

1. Overview

The API exposes three public capabilities:

1. Execute a time-series forecast.

2. Query the status of a specific execution run.

3. Check the service health status.

The API returns predictions within a forecast run resource that saves:

2. Authentication

The API uses an access key.

2.1 Accepted Formats

You can send the key in two ways:

2.2 Rules

2.3 Example

curl -X POST "https://your-domain/api/forecast" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_key" \
  -d '{"series":[1,2,3,4,5],"horizon":3}'

3. Endpoints

3.1 Execute Synchronous Forecast

POST /api/forecast

This endpoint runs the prediction within the same request.

Returns:

3.2 Execute Asynchronous Forecast

POST /api/forecast/async

This endpoint queues the prediction to be processed later.

Returns:

3.3 Query an Execution Run

GET /api/forecast-runs/{forecastRun}

Returns the current state of a specific execution run.

Returns:

3.4 Service Health

GET /api/health

Does not require an API key.

Used for basic monitoring of the stack.

4. Prediction Payload

4.1 Accepted Fields

{
  "series": [1, 2, 3, 4, 5],
  "horizon": 3,
  "frequency": "D",
  "model": "optional-model",
  "metadata": {}
}

4.2 Parameter Description

`series`

Example:

[10, 12, 13, 15, 18]

`horizon`

Example:

`frequency`

Common values:

If left undefined (null or omitted), the TimeSSeract engine will attempt to auto-detect the frequency using Fast Fourier Transform (FFT). This process strictly requires at least 14 historical data points in the series. Otherwise, it will return null due to insufficient samples to confidently trace seasonal patterns.

`metadata`

It does not modify calculations but travels with the request if your integration needs it.

5. API Response

The standard response returns an execution run resource.

5.1 Main Fields

5.2 Field Definitions

`status`

State of the execution.

Possible values:

`provider`

Logical forecast provider.

In this project, it is returned as timesfm.

`backend`

Actual backend that produced the response.

Common values:

`input_series`

Input series sent to the system.

`forecast`

Prediction results.

Usually contains:

`error_message`

Error message if execution failed.

If execution finished successfully, this field is null.

Timestamps

Values are formatted as ISO 8601 strings.

6. Response Examples

6.1 Correct Synchronous Response

{
  "data": {
    "id": 123,
    "status": "completed",
    "provider": "timesfm",
    "backend": "timesfm",
    "horizon": 3,
    "frequency": "D",
    "input_series": [1, 2, 3, 4, 5],
    "forecast": {
      "horizon": 3,
      "forecast": [5.8, 6.1, 6.4],
      "backend": "timesfm"
    },
    "error_message": null,
    "user_id": 10,
    "api_key_id": 4,
    "queued_at": "2026-07-01T12:00:00+00:00",
    "started_at": "2026-07-01T12:00:01+00:00",
    "completed_at": "2026-07-01T12:00:02+00:00",
    "created_at": "2026-07-01T12:00:00+00:00",
    "updated_at": "2026-07-01T12:00:02+00:00",
    "links": {
      "self": "https://your-domain/api/forecast-runs/123"
    }
  },
  "meta": {
    "mode": "sync"
  }
}

6.2 Asynchronous Response

{
  "data": {
    "id": 124,
    "status": "queued",
    "provider": "timesfm",
    "backend": "unknown",
    "horizon": 24,
    "frequency": null,
    "input_series": [10, 20, 30],
    "forecast": null,
    "error_message": null,
    "user_id": 10,
    "api_key_id": 4,
    "queued_at": "2026-07-01T12:10:00+00:00",
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-07-01T12:10:00+00:00",
    "updated_at": "2026-07-01T12:10:00+00:00",
    "links": {
      "self": "https://your-domain/api/forecast-runs/124"
    }
  },
  "meta": {
    "mode": "async"
  }
}

7. Common Errors

7.1 Missing API Key

{
  "message": "Missing API key."
}

HTTP:

7.2 Invalid or Revoked API Key

{
  "message": "Invalid API key."
}

HTTP:

7.3 Payload Validation

If required fields are missing or the format is invalid, Laravel returns validation errors.

Typical cases:

HTTP:

8. Integration Examples

8.1 JavaScript / TypeScript

type ForecastResponse = {
  data: {
    id: number;
    status: 'queued' | 'running' | 'completed' | 'failed';
    provider: string;
    backend: string;
    model: string | null;
    horizon: number;
    frequency: string | null;
    input_series: number[];
    forecast: unknown;
    error_message: string | null;
    links: { self: string };
  };
  meta: { mode: 'sync' | 'async' | 'status' };
};

async function forecast(series: number[], horizon = 3) {
  const response = await fetch('/api/forecast', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.TIMESFM_API_KEY ?? '',
    },
    body: JSON.stringify({ series, horizon }),
  });

  if (!response.ok) {
    throw new Error(`Forecast failed: ${response.status}`);
  }

  return (await response.json()) as ForecastResponse;
}

8.2 PHP

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => config('services.timesfm.api_key'),
])->post('https://your-domain/api/forecast', [
    'series' => [1, 2, 3, 4, 5],
    'horizon' => 3,
    'frequency' => 'D',
]);

if (! $response->successful()) {
    throw new RuntimeException('Forecast request failed');
}

$payload = $response->json();

9. Integration Best Practices

10. Quick Summary

The minimum required steps to consume the API are:

1. Send X-API-Key or Authorization: Bearer.

2. Do a POST /api/forecast with series and horizon.

3. Read data.forecast, data.backend, data.model, and data.status.

4. If using async, poll GET /api/forecast-runs/{id}.