Ingest records

Send observations into a data source. The data source must already exist (create it in the dashboard) and not be archived.

POST/v1/data_sources/ingest

Request body

The body names the target data source and carries a batch of records.

data_sourcestringRequired

The name of an existing, non-archived data source to write into.

recordsarrayRequired

A list of records to store. Each record is a single observation of one series at one time.

Record fields

timestampintegerRequired

Unix time in seconds.

namestringRequired

The series name. One data source holds many named series.

valuenumberRequired

The observed value (an integer or float).

Example request

This writes four orders observations into the store_metrics data source, reading the token from the environment:

curl https://api.temporis.co/v1/data_sources/ingest \
  -H "Authorization: Bearer $TEMPORIS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data_source": "store_metrics",
    "records": [
      { "timestamp": 1718841600, "name": "orders", "value": 42 },
      { "timestamp": 1718845200, "name": "orders", "value": 51 },
      { "timestamp": 1718848800, "name": "orders", "value": 47 },
      { "timestamp": 1718852400, "name": "orders", "value": 63 }
    ]
  }'
import os, requests

resp = requests.post(
    "https://api.temporis.co/v1/data_sources/ingest",
    headers={"Authorization": f"Bearer {os.environ['TEMPORIS_TOKEN']}"},
    json={
        "data_source": "store_metrics",
        "records": [
            {"timestamp": 1718841600, "name": "orders", "value": 42},
            {"timestamp": 1718845200, "name": "orders", "value": 51},
            {"timestamp": 1718848800, "name": "orders", "value": 47},
            {"timestamp": 1718852400, "name": "orders", "value": 63},
        ],
    },
)
resp.raise_for_status()  # 204 No Content on success
const resp = 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: 1718841600, name: "orders", value: 42 },
      { timestamp: 1718845200, name: "orders", value: 51 },
      { timestamp: 1718848800, name: "orders", value: 47 },
      { timestamp: 1718852400, name: "orders", value: 63 },
    ],
  }),
});

Response

On success the endpoint returns 204 No Content with an empty body:

204 No Content

Upsert behavior

Each record is keyed by the pair (timestamp, name). Re-sending a record with the same timestamp and series name overwrites the stored value.

Retries and backfills are idempotent

Because the write is an upsert, you can safely retry a failed request or re-send historical data — duplicates collapse onto the same key instead of accumulating.

Batching

Prefer sending many records in a single request over one record per request. Batching cuts round trips and overhead dramatically. When loading history, send it in chunks of many records each rather than streaming one point at a time.

Errors

Errors return the HTTP status plus a JSON body of the form { "detail": "..." }.

Statusdetail messageMeaning
401Invalid access token. / Missing access token.Authentication failed — check your token.
404Data source not found.The named data source does not exist. Create it in the dashboard first.
409Data source is archived.The data source is archived and cannot accept writes. Unarchive it or use another source.

See Errors & status codes for the complete reference.

Related

Data sources →

How Temporis stores your named series.

Create a prediction →

Forecast from the data you ingested.

Preparing data →

Get your series ready to forecast well.