Create & manage

Create a segment

name and workspace_id are required (workspace_id must match your X-Workspace-Id header), and the segment must declare at least one feature and one label to be trainable:

curl -X POST "$API_BASE/v1/segment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily sales view",
    "description": "Store demand drivers on a daily grid",
    "workspace_id": "'$WORKSPACE_ID'",
    "features": ["foot_traffic", "promo_active", "daily_sales"],
    "labels": ["daily_sales"],
    "interval": 86400,
    "tolerance": 43200,
    "live": true,
    "normalization_strategy": {
      "primary_strategy": "nearest_value",
      "fallback_strategies": ["previous_value", "zero"],
      "tolerance": 43200
    },
    "engineered_features": [
      {
        "name": "sales_ma7",
        "technique": "moving_average_7",
        "techniqueName": "Moving Average (7)",
        "sourceField": "daily_sales",
        "category": "Moving Averages"
      }
    ]
  }'

from predictai import PredictAI

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

data = client.segments.post_segment(json={
    "name": "Daily sales view",
    "description": "Store demand drivers on a daily grid",
    "workspace_id": WORKSPACE_ID,
    "features": ["foot_traffic", "promo_active", "daily_sales"],
    "labels": ["daily_sales"],
    "interval": 86400,
    "tolerance": 43200,
    "live": True,
    "normalization_strategy": {
        "primary_strategy": "nearest_value",
        "fallback_strategies": ["previous_value", "zero"],
        "tolerance": 43200,
    },
    "engineered_features": [
        {
            "name": "sales_ma7",
            "technique": "moving_average_7",
            "techniqueName": "Moving Average (7)",
            "sourceField": "daily_sales",
            "category": "Moving Averages",
        },
    ],
})

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

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

const data = await client.segments.postSegment({
  json: {
    name: "Daily sales view",
    description: "Store demand drivers on a daily grid",
    workspace_id: WORKSPACE_ID,
    features: ["foot_traffic", "promo_active", "daily_sales"],
    labels: ["daily_sales"],
    interval: 86400,
    tolerance: 43200,
    live: true,
    normalization_strategy: {
      primary_strategy: "nearest_value",
      fallback_strategies: ["previous_value", "zero"],
      tolerance: 43200,
    },
    engineered_features: [
      {
        name: "sales_ma7",
        technique: "moving_average_7",
        techniqueName: "Moving Average (7)",
        sourceField: "daily_sales",
        category: "Moving Averages",
      },
    ],
  },
});

{
  "data": {
    "uid": "3d8a17f2-…",
    "message": "Segment created successfully",
    "segment": { "uid": "3d8a17f2-…", "name": "Daily sales view", … }
  }
}

Request body

Field	Meaning
`name` required	Display name.
`workspace_id` required	Must match the `X-Workspace-Id` header.
`features` required	Input columns (signal keys). At least one.
`labels` required	Columns the model predicts. At least one.
`interval` optional	Seconds between grid rows. Defaults to `86400` (daily).
`tolerance` optional	How far a raw value may sit from a row and still bind to it. Defaults to `43200`.
`live` optional	Rolling window (`true`) vs fixed historical range (`false`, the default).
`tail_seconds` optional	How far back a live segment reaches. Defaults to `20044800` (~8 months).
`window_start` / `window_end` optional	ISO 8601 bounds for historical segments; omitted → tail fallback.
`time_zone` optional	Time zone for bucketing and calendar features. Defaults to `"UTC"`.
`normalization_strategy` optional	Global gap-fill strategy — see Normalization.
`segment_strategies` optional	Per-field strategy overrides, keyed by field name.
`engineered_features` optional	Derived columns — see Engineered features.
`data_sharing` optional	`private` (default), `org`, or `public_inference`.
`description` / `purpose` optional	Free-text metadata.
`feature_beliefs` / `feature_impact` / `feature_tier` / `feature_direction` optional	Per-column priors; hand-built segments default to full confidence.

Configurations are validated at create time: every referenced technique and strategy must come from the supported catalog, so a segment that can't be served is rejected up front rather than failing at training.

Errors

Status	Why	Example message
`400`	Missing field, workspace mismatch, no feature/label, or bad `data_sharing` value	`"Missing required field: name"`
`403`	No workspace access, or plan quota reached	`"Segment limit exceeded. Your plan allows 5 segments per workspace."`
`422`	Unsupported normalization strategy or engineered-feature technique	`"Segment configuration cannot be served: …. Pick a technique from the supported catalog."`

List segments

curl "$API_BASE/v1/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.segments.get_segment()

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

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

const data = await client.segments.getSegment();

{
  "data": {
    "segments": [
      {
        "uid": "3d8a17f2-…",
        "name": "Daily sales view",
        "features": ["foot_traffic", "promo_active", "daily_sales"],
        "labels": ["daily_sales"],
        "interval": 86400,
        "tolerance": 43200,
        "live": true,
        "created_at": "2026-07-15T08:30:00+00:00",
        …
      }
    ]
  }
}

Segments built by goal discovery are listed alongside your hand-built ones — they carry "origin": "discovery" and don't count against your quota.

Inspect one segment

curl "$API_BASE/v1/segment/$SEGMENT_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.segments.get_segment_by_segment_id(SEGMENT_ID)

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

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

const data = await client.segments.getSegmentBySegmentId(SEGMENT_ID);

{
  "data": {
    "segment": {
      "id": "3d8a17f2-…",
      "name": "Daily sales view",
      "configuration": {
        "interval": 86400,
        "tolerance": 43200,
        "tail_seconds": 20044800,
        "live": true,
        "time_zone": "UTC",
        …
      },
      "fields": {
        "features": [ { "name": "foot_traffic", "type": "number", "role": "feature" }, … ],
        "labels": [ { "name": "daily_sales", "type": "number", "role": "label" } ],
        "engineered_features": [ { "name": "sales_ma7", "technique": "moving_average_7", … } ],
        "total": 4
      },
      "normalization": { "global_strategy": { … }, "field_strategies": {} },
      "data_summary": {
        "estimated_signal_count": 2190,
        "time_range": { "start": "2025-11-20T…", "end": "2026-07-15T…", "duration_seconds": 20044800 }
      },
      "origin": null,
      …
    }
  }
}

The reported time_range is resolved exactly the way training and preview resolve it — what you see here is what a model would get.

Edit a segment

Send only the fields you're changing — the same fields as create, including nulling out normalization_strategy or engineered_features to remove them:

curl -X PUT "$API_BASE/v1/segment/$SEGMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{ "features": ["foot_traffic", "promo_active", "weather_temp_c", "daily_sales"] }'

from predictai import PredictAI

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

data = client.segments.put_segment_by_segment_id(SEGMENT_ID, json={
    "features": [
        "foot_traffic",
        "promo_active",
        "weather_temp_c",
        "daily_sales",
    ],
})

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

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

const data = await client.segments.putSegmentBySegmentId(SEGMENT_ID, {
  json: {
    features: [
      "foot_traffic",
      "promo_active",
      "weather_temp_c",
      "daily_sales",
    ],
  },
});

{ "data": { "message": "Segment updated successfully" } }

Every referenced feature and label must exist in the workspace, the edited segment must still have at least one feature and one label, and the whole edited configuration is re-validated against the supported catalog.

Editing a segment changes what future trainings and previews see — it does not retroactively change trainings that already ran. Pipelines using the segment pick up the new shape on their next run.

Errors

Status	Why	Example message
`400`	Empty body, invalid strategy object, or the edit would leave the segment untrainable	`"normalization_strategy must be an object"`
`403`	Not the segment's owner, or feature/label count exceeds your plan	`"Your plan allows a maximum of 20 features per segment. …"`
`404`	Segment not found in this workspace	`"Segment not found"`
`422`	A referenced key doesn't exist, or an unsupported technique	`"The following features don't exist in workspace signals: weather_temp_c"`

Delete a segment

curl -X DELETE "$API_BASE/v1/segment/$SEGMENT_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.segments.delete_segment_by_segment_id(SEGMENT_ID)

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

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

const data = await client.segments.deleteSegmentBySegmentId(SEGMENT_ID);

{ "data": { "message": "Segment deleted successfully" } }

A segment referenced by one or more pipelines can't be deleted — you'll get a 409 naming them (e.g. "Cannot delete segment because it is being used by 2 model(s): Daily sales forecaster, Weekly planner"). Delete or re-point those pipelines first.

On this page