Predictions & sampling

A prediction request returns several possible futures rather than one. This page explains how to read the response and how the sampling controls shape it. For the exact schema see the predict reference.

Anatomy of a request

You predict against a data profile, not a raw data source. The profile already knows which series to read and how to encode them, so a request only has to say which profile and how to sample. Four fields cover it:

Here is a request for 20 trajectories against the hourly_orders profile:

curl https://api.temporis.co/v1/predict \
  -H "Authorization: Bearer ts_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "data_profile": "hourly_orders",
    "count": 20,
    "temperature": 1.0,
    "top_p": 0.9
  }'

import requests

resp = requests.post(
    "https://api.temporis.co/v1/predict",
    headers={"Authorization": "Bearer ts_your_token"},
    json={
        "data_profile": "hourly_orders",
        "count": 20,
        "temperature": 1.0,
        "top_p": 0.9,
    },
)
resp.raise_for_status()
result = resp.json()

const resp = await fetch("https://api.temporis.co/v1/predict", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ts_your_token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    data_profile: "hourly_orders",
    count: 20,
    temperature: 1.0,
    top_p: 0.9,
  }),
});
const result = await resp.json();

The full reference — every field, status code, and error message — is in the predict endpoint reference.

Reading the response

A successful call returns HTTP 200 with four top-level fields:

The example below shows two of the trajectories from an orders forecast. The profile's interval is 3600 and its patch_spacing is 2, so rows step by interval × patch_spacing = 7200 seconds (two hours):

{
  "request_id": "9f3c1a7e2b4d",
  "data_profile": "hourly_orders",
  "predict_from": 1718888400,
  "predictions": [
    {
      "loss": 0.84,
      "data": [
        { "timestamp": 1718895600, "orders": 142.0 },
        { "timestamp": 1718902800, "orders": 137.5 }
      ]
    },
    {
      "loss": 1.07,
      "data": [
        { "timestamp": 1718895600, "orders": 151.2 },
        { "timestamp": 1718902800, "orders": 129.8 }
      ]
    }
  ]
}

Each row has a timestamp plus one field per series the profile reads — here just orders. The timestamps step by interval × patch_spacing seconds, the same spacing for every trajectory, so you can align samples row by row.

The sampling controls

Three parameters shape the set of futures you get back. They trade resolution and diversity against cost and stability.

Loss: ranking trajectories

Every prediction carries a loss. Lower means the model considered that trajectory more typical — more in line with what it expected given the history. Higher-loss paths are still valid samples; they are just less central.

Use loss to pick a single representative trajectory, or as a weight when you summarize the set. To grab the most typical path:

best = min(result["predictions"], key=lambda p: p["loss"])

Multivariate predictions

If a profile reads several series names, each forecast row carries one field per name — the series are predicted jointly, so their values stay consistent within a row. A profile reading kw and price together returns rows like:

{ "timestamp": 1718895600, "kw": 482.0, "price": 31.7 }

Public data profiles

You can predict against shared profiles that Temporis maintains, with no setup of your own — just pass the public name as data_profile:

{ "data_profile": "temporis/polymarket", "count": 20, "temperature": 1.0, "top_p": 0.9 }

The response shape is identical; the series fields in each row match whatever the public profile reads.

Related