Request shapes, types, and defaults below come from the archived schema-version-5 build
0136121. Behavior notes describe separate checks on build af6670b on 6 November 2026. These sources describe different builds. Check the target deployment’s host-root /version; the value API reference records the source coverage.Send an observation batch
SendPOST /api/v1/domains/{domain_id}/value/observe with a nonempty session_id and an observations array. The schema permits at most 50 observations per request. Use "session_id": "ignored" on the authenticated hosted service as described in HTTP and contracts.
This complete request body shows one supplied target with numeric policy features. Replace the illustrative IDs, feature names, and values with the encoding used by your configured value learner.
Value observation request
application_outcomes, an array of at most 50 application-evaluation records. Those records have case_id, context_sha256, model_sha256, and utility; they are separate from supervised observations. See application promotion for their contract.
Choose one supervision source
Each observation sent tovalue/observe carries exactly one of target, outcome, or continuation. Omit the other two fields.
A row with conflicting or missing supervision rejects the whole observation batch with HTTP
422. The observed error is:
Identify the record and its inputs
Keeprecord_id, episode_id, and step alongside the state representation. record_id identifies a particular observation; episode_id and step identify its place in the recorded sequence.
The observation schema rejects additional top-level fields. The object and relation entries allow application-defined properties. The schema specifies the types and defaults of the representation controls but does not define their full projection behavior.
The
projected representation reduces objects and relations to counts. The object_graph representation retains the objects and the relations between them. The comparison-group workflow below uses the graph path. Configure the representation before collecting the observations for a fit; see value learning.
Provided target
This supervision fragment identifies an application-provided value. Combine it with the state’s required inputs and the fullvalue/observe request envelope.
Provided-target observation fragment
Observed outcome
Anoutcome requires value and terminal_step. Its value, discount, and neutral are numbers in [0, 1]; terminal_step is a nonnegative number. discount defaults to 1 and neutral to 0.5. Discounting moves the recorded terminal value toward the neutral value for earlier states. With discount: 1, that distance from the neutral value is unchanged.
Observed-outcome observation fragment
[0, 1] range and supplies the actual episode boundaries.
Build continuation observations
Your application supplies legal successor states. The server evaluates unfinished successors with a fitted reference model and uses these evaluations to construct the continuation target. A completed successor carries its exactterminal_value, which takes precedence over the model’s estimate.
In the construction fragment below, recorded_state is the current state’s supported descriptor. legal_successors is the list of successor descriptors generated by the application’s rules or transition interface.
Continuation observation construction fragment
maximizing is a required Boolean. The successors array requires 1 to 256 entries per continuation row. The continuation schema defaults discount to 1 and neutral to 0.5, with both constrained to [0, 1]. Set maximizing for the value perspective used by this comparison and keep successor values in that perspective.
Supply the legal alternatives intended for the backup. If that set exceeds the per-row schema limit, resolve the integration contract instead of silently dropping alternatives.
For a completed successor, attach the exact score to its descriptor:
Terminal successor construction fragment
terminal_value is a number in [0, 1]. Successor descriptors use the same numeric maps, object arrays, relation arrays, and representation flags as a value input. They can also carry an optional counterpart in the ValueInput shape; the schema alone does not establish how an evaluator combines the two perspectives.
Place the constructed observation in the observations array of the complete request envelope above. Preserve the real recorded outcome separately in your application record when the continuation is an estimated target.
Satisfy the fitting prerequisites
Each refusal above was returned as HTTP
422. The aggregate per-fit successor cap is separate from the schema limit of 256 successors per observation. Its exact value, whether terminal successors count toward it, and a route for inspecting it are not established by the available contract. Do not infer a supported aggregate limit from the size of one successful request. When reducing or sampling comparison groups, preserve the evidence and group coverage required in both partitions.
Declare comparisons between alternatives
Rows sharingmetadata.comparison_group belong to the same comparison group in the observed graph workflow. A continuation’s successors array does not create a comparison group by itself.
Use one observation per alternative child of a recorded parent state. Each child’s row describes that child and carries its own continuation over that child’s successors. Give the sibling rows the same parent comparison identifier, while preserving distinct record_id values.
Sibling identity fragments
comparison_weight to add the comparison contribution; its default is 0. A positive weight does not create missing groups. The training guide explains the options and report fields.
The checked arrangement used continuation supervision for sibling rows. Mixed target, outcome, and continuation supervision within one group has not been characterized by these checks.
Keep a blended target explicit
The coupled learning and planning method describes targets of the formy = λu + (1 − λ)z̄, where u is a planning assessment and z̄ is a discounted observed outcome.
If your application computes this scalar, send the result as target. It then enters as a provided target, rather than a continuation that the server refreshes from successors. Retain the observed outcome, assessment, blend settings, and reference-model identity in the application record so you can reconstruct the calculation.
The inspected interface does not expose a λ field. Matching episode_id and step on separate rows does not establish an automatic blend. Neither continuation.discount nor neutral is documented as a λ control. Keeping outcome rows and continuation rows in the same fit preserves both kinds of examples; it does not by itself reproduce a per-row blended target.
Retry identical observations
value/observe uses record_id to recognize identical replays. An accepted replay contributes to duplicates; reusing the ID with changed content returns HTTP 409.
After an uncertain upload, resend the identical records with their original IDs, then check that accepted + duplicates accounts for every submitted row. Treat a changed observation as a distinct record with a new ID. Do not change a target under an existing ID and expect the request to update it in place.
This rule belongs to value observations. Domain feedback has a different retry contract; see operations and retries.
Verify admission and target refresh
The observation response reportstarget_sources.model_continuation and target_sources.provided_or_observed. These counters identify admitted source types. Inspect the subsequent fit through value/state and training.report.target_refresh to verify the target work used by training.
An accepted upload alone does not show that a later training scope included its rows. Check target refresh, supervision scope, and comparison coverage together.