Quickstart

This guide takes you from a fresh account to your first forecast. You'll create an API key, register a data source, stream in some history, build a data profile, and call the prediction endpoint. Budget about five minutes.

1. Create an access token

   In the dashboard, open Access Tokens and create one. The token is shown once — copy it immediately. It looks like ts_… and authenticates every API request.

   Store it as an environment variable so the examples below work as-is:

   export TEMPORIS_TOKEN="ts_your_token_here"

2. Add a payment method

   Prediction is metered per token of usage, so a card on file is required before /v1/predict will run. Add one under Billing. Ingesting data does not require billing — only forecasting does.

3. Create a data source

   Under Data Sources, create one named store_metrics. Names must start with a lowercase letter and contain only lowercase letters, digits, and underscores. A data source is an empty container until you send it data.

4. Send some history

   Each record is a (timestamp, name, value) triple. The timestamp is a Unix time in seconds, name is the series, and value is the number. Here we send a handful of hourly orders readings; in practice you'd send as much real history as you have.

   curl -X POST "https://api.temporis.co/v1/data_sources/ingest" \
     -H "Authorization: Bearer $TEMPORIS_TOKEN" \
     --json '{
       "data_source": "store_metrics",
       "records": [
         { "timestamp": 1716249600, "name": "orders", "value": 42 },
         { "timestamp": 1716253200, "name": "orders", "value": 51 },
         { "timestamp": 1716256800, "name": "orders", "value": 47 },
         { "timestamp": 1716260400, "name": "orders", "value": 63 }
       ]
     }'

   import os, requests
   
   headers = {"Authorization": f"Bearer {os.environ['TEMPORIS_TOKEN']}"}
   
   resp = requests.post(
       "https://api.temporis.co/v1/data_sources/ingest",
       headers=headers,
       json={
           "data_source": "store_metrics",
           "records": [
               {"timestamp": 1716249600, "name": "orders", "value": 42},
               {"timestamp": 1716253200, "name": "orders", "value": 51},
               {"timestamp": 1716256800, "name": "orders", "value": 47},
               {"timestamp": 1716260400, "name": "orders", "value": 63},
           ],
       },
   )
   resp.raise_for_status()  # 204 No Content on success

   const res = await fetch("https://api.temporis.co/v1/data_sources/ingest", {
     method: "POST",
     headers: {
       "Authorization": `Bearer ${process.env.TEMPORIS_TOKEN}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       data_source: "store_metrics",
       records: [
         { timestamp: 1716249600, name: "orders", value: 42 },
         { timestamp: 1716253200, name: "orders", value: 51 },
         { timestamp: 1716256800, name: "orders", value: 47 },
         { timestamp: 1716260400, name: "orders", value: 63 },
       ],
     }),
   });
   if (!res.ok) throw new Error(`Ingest failed: ${res.status}`);

   A successful ingest returns 204 No Content — an empty body. Sending the same (timestamp, name) again simply overwrites the value, so retries and backfills are safe. See Ingest records for the details.

5. Build a data profile

   Back in the dashboard, open Data Profiles and create one called hourly_orders. Point it at the store_metrics data source, select the orders series, and set the interval to 3600 seconds (one hour). The defaults for everything else are a fine starting point.

   A profile needs a baseline of history before Temporis can prepare it for serving. Once it has enough data, the dashboard marks it ready. Until then, predictions return a "not ready" error — that's expected.

6. Generate a forecast

   Now ask the profile for what comes next. count is how many independent future trajectories to draw; temperature and top_p control how adventurous the sampling is.

   curl -X POST "https://api.temporis.co/v1/predict" \
     -H "Authorization: Bearer $TEMPORIS_TOKEN" \
     --json '{
       "data_profile": "hourly_orders",
       "count": 5,
       "temperature": 1.0,
       "top_p": 0.9
     }'

   forecast = requests.post(
       "https://api.temporis.co/v1/predict",
       headers=headers,
       json={
           "data_profile": "hourly_orders",
           "count": 5,
           "temperature": 1.0,
           "top_p": 0.9,
       },
   ).json()
   
   best = min(forecast["predictions"], key=lambda p: p["loss"])
   for row in best["data"]:
       print(row["timestamp"], row["orders"])

   const res = await fetch("https://api.temporis.co/v1/predict", {
     method: "POST",
     headers: {
       "Authorization": `Bearer ${process.env.TEMPORIS_TOKEN}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       data_profile: "hourly_orders",
       count: 5,
       temperature: 1.0,
       top_p: 0.9,
     }),
   });
   const forecast = await res.json();
   const best = forecast.predictions
     .reduce((a, b) => (a.loss < b.loss ? a : b));
   console.table(best.data);

   The response gives you the forecast origin and one trajectory per sample:

   {
     "request_id": "9f2c1a7e8b6d4f03a1c5e9d2b7f40a18",
     "data_profile": "hourly_orders",
     "predict_from": 1716260400,
     "predictions": [
       {
         "loss": 0.83,
         "data": [
           { "timestamp": 1716264000, "orders": 58.2 },
           { "timestamp": 1716267600, "orders": 61.9 },
           { "timestamp": 1716271200, "orders": 49.4 }
         ]
       }
       // ... four more sampled trajectories
     ]
   }

What just happened

You streamed observations into a data source, described how to read them with a data profile, and drew five possible futures from /v1/predict. Each prediction is a complete trajectory; together they form a probabilistic picture of what comes next. The lower a prediction's loss, the more typical the model considered that trajectory.

Next steps