History & usage

List past inferences, audit a single one, and chart a deployment's request volume.

Every inference is recorded. Use the history to audit forecasts after the fact, debug a surprising prediction, or track how much a deployment is being called.

List inferences

curl "$API_BASE/v1/inference?page=1&limit=20&inference_type=segment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

from predictai import PredictAI

client = PredictAI(token="pa_live_…", workspace_id="ws_…")

data = client.inference.get_inference(params={"page": 1, "limit": 20, "inference_type": "segment"})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…", workspaceId: "ws_…" });

const data = await client.inference.getInference({
  params: { page: 1, limit: 20, inference_type: "segment" },
});

{
  "inferences": [
    {
      "uid": "b7e6…",
      "user_id": "USER_ID",
      "model_id": "9f2c41d8-…",
      "training_id": "7d81c3f0-…",
      "deployment_id": "c4a7…",
      "deployment_type": "shared",
      "timestamp": "2026-07-15T12:04:45.123000+00:00",
      "inference_type": "segment",
      "request": { … },
      "response": {
        "success": true,
        "predictions": [
          { "label": "daily_sales", "point": [1250.75, 1274.1, …] }
        ],
        "output_shape": null,
        "error": null
      },
      "performance": { "latency_ms": 245.67, "status_code": 200 },
      "segment_metadata": {
        "segment_id": "SEGMENT_ID",
        "segment_name": "Retail daily",
        "sequence_length": 15,
        "feature_names": ["website_visitors", "marketing_spend", …],
        …
      },
      "deployment_label": "chronos_bolt / base",
      "segment_name": "Retail daily"
    }
  ],
  "history_by_segment": {
    "SEGMENT_ID": {
      "interval_seconds": 86400,
      "labels": { … },
      "row_count": 64
    }
  },
  "pagination": { "page": 1, "limit": 20, "total": 312, "total_pages": 16 }
}

List rows are trimmed for scanning: prediction arrays are capped to 64 points and the first 3 labels. Fetch the record by uid for the full payload.

Query parameters

Parameter	Meaning
`page` optional	Page number (1-indexed). Defaults to `1`.
`limit` optional	Rows per page, max 100. Defaults to `20`.
`deployment_id` optional	Filter to a single deployment.
`inference_type` optional	`segment` or `raw`.
`sort_direction` optional	`asc` or `desc` (default) on timestamp.

Inspect one inference

curl "$API_BASE/v1/inference/$INFERENCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

from predictai import PredictAI

client = PredictAI(token="pa_live_…", workspace_id="ws_…")

data = client.inference.get_inference_by_inference_id(INFERENCE_ID)

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…", workspaceId: "ws_…" });

const data = await client.inference.getInferenceByInferenceId(INFERENCE_ID);

{
  "inference": {
    "uid": "b7e6…",
    "deployment_id": "c4a7…",
    "timestamp": "2026-07-15T12:04:45.123000+00:00",
    "inference_type": "segment",
    "request": { … },
    "response": { "success": true, "predictions": [ … ], … },
    "performance": { "latency_ms": 245.67, "status_code": 200 },
    "segment_metadata": { … },
    "deployment": { "uid": "c4a7…", "deployment_type": "shared", … },
    "segment": { "uid": "SEGMENT_ID", "name": "Retail daily", … },
    "deployment_label": "chronos_bolt / base",
    "segment_name": "Retail daily",
    "model_metrics": {
      "accuracy_score": 0.94,
      "skill_score": 0.61,
      "score_kind": "wmape",
      "model_name": "Daily sales forecaster"
    },
    "history": {
      "daily_sales": {
        "timestamps": ["2026-06-30T00:00:00.000000Z", …],
        "values": [1201.5, 1187.0, …]
      }
    },
    "history_meta": {
      "interval_seconds": 86400,
      "labels": ["daily_sales"],
      "row_count": 256
    }
  }
}

The detail record is the audit view of a forecast:

history is the segment window the model actually saw at inference time, keyed by label — not the segment's current data. Chart it to the left of the predictions to see what the model was extrapolating from.
model_metrics carries the deployed training's held-out accuracy_score and skill_score, so you can judge how much to trust the forecast. See the report.
The resolved deployment and segment documents are inlined — no follow-up calls needed.

Lookups are scoped to the workspace on X-Workspace-Id; an inference from another workspace returns the same 404 as a missing one.

Deployment usage

Request volume over time for one deployment:

curl "$API_BASE/v1/inference/deployments/$DEPLOYMENT_ID/usage?period=7d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

from predictai import PredictAI

client = PredictAI(token="pa_live_…", workspace_id="ws_…")

data = client.inference.get_inference_deployments_by_deployment_id_usage(DEPLOYMENT_ID, params={"period": "7d"})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…", workspaceId: "ws_…" });

const data = await client.inference.getInferenceDeploymentsByDeploymentIdUsage(DEPLOYMENT_ID, { params: { period: "7d" } });

{
  "deployment_id": "c4a7…",
  "model_id": "9f2c41d8-…",
  "deployment_type": "shared",
  "period": "7d",
  "bin_size": "hour",
  "start_time": "2026-07-08T12:00:00Z",
  "end_time": "2026-07-15T12:00:00Z",
  "usage_over_time": [
    { "timestamp": "2026-07-08T12:00:00Z", "requests": 42 },
    { "timestamp": "2026-07-08T18:00:00Z", "requests": 57 },
    …
  ]
}

Parameter	Meaning
`period` optional	Window: `24h` (default), `7d`, `30d`, or `all`.
`bin_size` optional	Bin granularity: `hour`, `day`, or `week`. Auto-selected from the period if omitted.

Errors

Status	Code	Why
`400`	`BAD_REQUEST`	`X-Workspace-Id` header missing, or `page`/`limit` aren't integers
`401`	`UNAUTHORIZED`	Token missing or invalid
`403`	`FORBIDDEN`	No access to the deployment (usage route)
`404`	`NOT_FOUND`	Inference not found in this workspace
`500`	`INTERNAL_ERROR`	Unexpected server error

List inferences

Query parameters

Inspect one inference

Deployment usage

Errors

On this page