Preview

See the actual rows a segment produces — including dry runs of configurations you haven't saved yet.

Preview returns the segment's real, materialized table — grid, window, normalization, and engineered features all applied. It's the same resolution path training uses, so what you see is exactly what a model would get.

Preview a saved segment

curl -X POST "$API_BASE/v1/segment/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{ "segment_id": "'$SEGMENT_ID'", "page": 1, "page_size": 100 }'

from predictai import PredictAI

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

data = client.segments.post_segment_preview(json={"segment_id": SEGMENT_ID, "page": 1, "page_size": 100})

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

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

const data = await client.segments.postSegmentPreview({
  json: { segment_id: SEGMENT_ID, page: 1, page_size: 100 },
});

{
  "data": {
    "data": {
      "timestamp": ["2026-07-13T00:00:00.000000Z", "2026-07-14T00:00:00.000000Z", …],
      "foot_traffic": [1841, 1904, …],
      "promo_active": [0, 1, …],
      "sales_ma7": [11980.2, 12111.5, …],
      "daily_sales": [12100.0, 12841.5, …]
    },
    "pagination": {
      "total_rows": 232,
      "total_pages": 3,
      "current_page": 1,
      "requested_page": 1,
      "page_size": 100
    },
    "time_range": { "start": "2025-11-20T…", "end": "2026-07-15T…", "duration_seconds": 20044800 },
    "field_info": { "features": [ … ], "labels": [ … ], "engineered_features": [ … ], … },
    "segment_info": { "id": "3d8a17f2-…", "name": "Daily sales view", "interval_seconds": 86400, … }
  }
}

Request body

Field	Meaning
`segment_id` required	The saved segment to materialize. Omit it only when dry-running an inline `config` (below).
`config` optional	An inline segment configuration instead of `segment_id` — see Dry-run.
`page` optional	Page number, ≥ 1. Defaults to `1`.
`page_size` optional	Rows per page, capped at `500`. Defaults to `100`.

Response fields

Field	Meaning
`data`	Column-oriented rows: one array per column, aligned by index with `timestamp`.
`pagination`	Out-of-range pages are clamped to the last valid page — compare `requested_page` with `current_page`.
`time_range`	The resolved window — identical to what training would use.
`field_info` / `segment_info`	The segment's fields and configuration, echoed for display.

Dry-run an unsaved configuration

Pass an inline config instead of segment_id and preview a segment design before saving it — this is the fastest way to iterate on grid, normalization, and engineered-feature choices:

curl -X POST "$API_BASE/v1/segment/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "workspace_id": "'$WORKSPACE_ID'",
      "features": ["foot_traffic", "daily_sales"],
      "labels": ["daily_sales"],
      "interval": 86400,
      "tolerance": 43200,
      "normalization_strategy": {
        "primary_strategy": "linear_interpolation",
        "fallback_strategies": ["previous_value"]
      },
      "engineered_features": [
        { "name": "sales_lag1", "technique": "lag_1", "sourceField": "daily_sales" }
      ]
    },
    "page": 1,
    "page_size": 50
  }'

from predictai import PredictAI

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

data = client.segments.post_segment_preview(json={
    "config": {
        "workspace_id": WORKSPACE_ID,
        "features": ["foot_traffic", "daily_sales"],
        "labels": ["daily_sales"],
        "interval": 86400,
        "tolerance": 43200,
        "normalization_strategy": {
            "primary_strategy": "linear_interpolation",
            "fallback_strategies": ["previous_value"],
        },
        "engineered_features": [
            {
                "name": "sales_lag1",
                "technique": "lag_1",
                "sourceField": "daily_sales",
            },
        ],
    },
    "page": 1,
    "page_size": 50,
})

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

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

const data = await client.segments.postSegmentPreview({
  json: {
    config: {
      workspace_id: WORKSPACE_ID,
      features: ["foot_traffic", "daily_sales"],
      labels: ["daily_sales"],
      interval: 86400,
      tolerance: 43200,
      normalization_strategy: {
        primary_strategy: "linear_interpolation",
        fallback_strategies: ["previous_value"],
      },
      engineered_features: [
        {
          name: "sales_lag1",
          technique: "lag_1",
          sourceField: "daily_sales",
        },
      ],
    },
    page: 1,
    page_size: 50,
  },
});

An inline config must include features, interval, tolerance, and workspace_id. Unsupported configurations return 422 before any data is read — the same validation as create, so a config that previews will also save.

A good workflow:

Check your fields and their cadences in the signal list.
Dry-run a config here; sanity-check gaps, fills, and engineered columns in the returned rows.
Create the segment with the config you settled on.

Errors

Status	Why	Example message
`400`	Neither `segment_id` nor a config, or a config missing required fields	`"Either segment_id or segment configuration must be provided"`
`403`	The segment belongs to someone else	`"Not authorized to access this segment"`
`404`	Unknown `segment_id` in this workspace	`"Segment not found"`
`422`	The configuration references an unsupported strategy or technique	`"Segment configuration cannot be served: …"`

Preview a saved segment

Request body

Response fields

Dry-run an unsaved configuration

Errors

On this page