Traffic demand

	Value
model_family	demand
Status	Served
Current release	demand-pool-quantiles-v1
Forecasts	offered_bytes p10, p50, p99
Horizons	10 to 60 minutes, in 10 minute intervals
Entity	Pool

Overview

Forecasts the bytes a pool will be offered in each 10 minute interval of the next hour, as a median with p10 and p99 bounds. It reads the daily and weekly pattern in the pool's last 7 days of pool_interval history, written with POST /telemetry, and returns forecasts through GET /predictions with model_family=demand.

Intended use and out-of-scope use

Intended use:

• Planning capacity for the next hour per pool, with p99 as the provisioning bound.
• Spotting a pool that is about to carry more or less than usual for the time of day.

Out of scope:

• Horizons beyond 60 minutes.
• Pools with less than 7 complete days of history. They are declined, not forecast.
• Instantaneous throughput or per-flow demand. The forecast is bytes per 10 minute interval per pool.
• Treating forecasts from synthetic history as qualified. They are marked unqualified.

Inputs

Write one pool_interval record per pool per 10 minute interval, tagged entity_id with the pool ID you later pass in link_ids.

Field or tag	Unit	Required	Description
inlet_bytes (field)	bytes	Yes	Bytes newly offered during the interval, not a running total.
boundary_id (tag)	none	Yes	Boundary the traffic crosses.
direction (tag)	none	Yes	Traffic direction, up or down.
evidence_kind (tag)	none	Yes	public_flow_estimate for measured traffic, synthetic_offered for synthetic traffic.

	Value
Measurement	pool_interval
Cadence	One record per 10 minute interval, timestamped on the UTC grid (:00, :10, :20, ...).
Required history	7 complete days: 1,008 consecutive intervals. One missing interval declines the pool until the gap ages out of the window.
Identity	boundary_id, direction, and evidence_kind stay unchanged for the whole 7 days.
Time	UTC.

A new pool forecasts 7 days after it starts reporting, or immediately after a 7 day backfill.

{
  "measurement": "pool_interval",
  "time": "2026-10-04T12:10:00Z",
  "tags": {
    "entity_id": "pool-1",
    "boundary_id": "inlet",
    "direction": "up",
    "evidence_kind": "public_flow_estimate"
  },
  "fields": { "inlet_bytes": 2150000000 }
}

Outputs

One item per pool and horizon:

Field	Unit	Description
offered_bytes_p50	bytes	Median forecast of bytes offered in the interval.
offered_bytes_p10	bytes	10th percentile forecast.
offered_bytes_p99	bytes	99th percentile forecast.

	Value
Horizons	10, 20, 30, 40, 50, and 60 minutes, counted from an issue time on the 10 minute grid.
Cadence	Issue times align to the 10 minute grid. Check predicted_at for each item's age.
demand block	The pool's identity tags, the forecast window, and a qualification_status.
Provenance	Each item carries model_version, feature_view_id, and model_release_id. Keep them with exported results.

Request forecasts

curl --fail-with-body -sS \
  -H "x-api-key: $CONSTELLATION_API_TOKEN" \
  "https://api.constellation.space/predictions?model_family=demand&link_ids=pool-1"

From an AI agent, call get_predictions on the MCP server with model_family set to demand and the same IDs in link_ids. Both need a key with predictions:read. GET /predictions describes the response and per-entity errors.

Declines

A pool can be declined for:

Reason	Cause
incomplete_telemetry	An interval is missing in the seven-day window.
missing_pool_identity	boundary_id, direction, or evidence_kind is missing.
ambiguous_series	An identity tag changed within the window, so the pool has more than one history.
uncalibrated_population	evidence_kind is not one the release is calibrated for.

Demand declines currently reach the API response with a null code and a generic message; until that is fixed, check the pool against this table.

Tiers

A fidelity tier labels how a model is served, not what a plan includes. This model is served at Bronze, by demand-pool-quantiles-v1. Silver and Gold are not served yet.

Every plan calls the same release: plans differ in allowance, not in tier. GET /predictions takes no tier parameter.

Method and version

The current release, demand-pool-quantiles-v1, forecasts quantiles from the pool's own history: the trailing day, the matching windows on each prior day, and the 7 day mean of inlet_bytes, together with the pool's identity tags.

Limitations and known failure modes

• Gaps decline the pool. One missing interval in the 7 day window declines it until the gap ages out.
• Identity changes split history. Changing boundary_id, direction, or evidence_kind within the window declines the pool as ambiguous_series.
• Uncommon events. The forecast follows the pool's daily and weekly pattern; a one-off surge that history has not shown is not anticipated.
• Synthetic history. Forecasts from synthetic_offered history are unqualified.

Changelog

Release	Change
demand-pool-quantiles-v1	Current served release.