> ## Documentation Index > Fetch the complete documentation index at: https://docs.together.ai/llms.txt > Use this file to discover all available pages before exploring further. # Forward-backward pass > Submits a forward-backward pass operation that will asynchronously compute gradients via backpropagation. ## OpenAPI ````yaml openapi.yaml POST /rl/training-sessions/{session_id}/operations/forward-backward openapi: 3.1.0 info: title: Together APIs description: The Together REST API. See https://docs.together.ai for more details. version: 2.0.0 termsOfService: https://www.together.ai/terms-of-service contact: name: Together Support url: https://www.together.ai/contact license: name: MIT url: https://github.com/togethercomputer/openapi/blob/main/LICENSE servers: - url: https://api.together.ai/v1 description: Default environment for APIs - url: https://api-inference.together.ai/v2 description: Optimized environment for inference security: - bearerAuth: [] paths: /rl/training-sessions/{session_id}/operations/forward-backward: post: tags: - RL summary: Forward-backward pass description: >- Submits a forward-backward pass operation that will asynchronously compute gradients via backpropagation. operationId: forwardBackward parameters: - name: session_id in: path required: true schema: description: Training session ID type: string - name: Idempotency-Key in: header required: true schema: description: >- Required key that makes retries return the original operation; use a new key for changed request bodies. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RL.ForwardBackwardBody' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RL.ForwardBackwardOperation' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/ErrorData' components: schemas: RL.ForwardBackwardBody: type: object required: - samples - loss properties: samples: description: Batch of training samples to process type: array items: $ref: '#/components/schemas/RL.TrainingSample' type: object loss: $ref: '#/components/schemas/RL.LossConfig' description: Loss function configuration return_loss_fn_outputs: type: boolean example: true description: >- Return the loss function's per-sample output tensors alongside the loss and metrics. Defaults to false. Enabling it increases the response size substantially for large batches and reduces step throughput, so leave it unset for ordinary training steps. forward_only: type: boolean example: true description: >- Run the forward pass only: report the loss and metrics, and the per-sample outputs when requested, without accumulating gradients. Defaults to false. Pair it with `return_loss_fn_outputs` to score a batch and read back its per-token log-probabilities. RL.ForwardBackwardOperation: type: object description: Async forward-backward pass operation required: - id - status properties: id: type: string example: 550e8400-e29b-41d4-a716-446655440000 description: Operation ID status: $ref: '#/components/schemas/RL.TrainingOperationStatus' example: TRAINING_OPERATION_STATUS_PENDING description: Operation status output: $ref: '#/components/schemas/RL.ForwardBackwardResult' description: Result on success error: $ref: '#/components/schemas/RL.TrainingOperationError' description: Error details on failure ErrorData: type: object required: - error properties: error: type: object properties: message: type: string nullable: false type: type: string nullable: false param: type: string nullable: true default: null code: type: string nullable: true default: null required: - type - message RL.TrainingSample: type: object required: - model_input - loss_fn_inputs properties: model_input: $ref: '#/components/schemas/RL.ModelInput' description: Model input loss_fn_inputs: type: object description: >- Per-token loss tensors keyed by name. Include `target_tokens` and the inputs required by the selected loss. Each tensor must declare `int64` or `float32`, be one-dimensional, and have the same length. additionalProperties: $ref: '#/components/schemas/RL.TensorData' routed_experts_key: type: string description: >- Opaque key returned with a sampled sequence. Pass it unchanged with the corresponding training sample to reuse the same expert selections. The selections must cover the entire training sample or all but its final token. Training fails if the key is no longer available. minLength: 1 maxLength: 256 pattern: ^routing/[A-Za-z0-9._-]+/[0-9a-f]{32}\.[1-9][0-9]*$ RL.LossConfig: type: object required: - type properties: type: $ref: '#/components/schemas/RL.LossType' description: Type of loss function to use example: LOSS_TYPE_GRPO cross_entropy_params: $ref: '#/components/schemas/RL.CrossEntropyLossParams' grpo_params: $ref: '#/components/schemas/RL.GRPOLossParams' ppo_params: $ref: '#/components/schemas/RL.PPOLossParams' cispo_params: $ref: '#/components/schemas/RL.CISPOLossParams' dro_params: $ref: '#/components/schemas/RL.DROLossParams' dppo_params: $ref: '#/components/schemas/RL.DPPOLossParams' description: >- Parameters for DPPO loss. Only valid when `type` is `LOSS_TYPE_DPPO`. RL.TrainingOperationStatus: type: string enum: - TRAINING_OPERATION_STATUS_UNSPECIFIED - TRAINING_OPERATION_STATUS_PENDING - TRAINING_OPERATION_STATUS_RUNNING - TRAINING_OPERATION_STATUS_COMPLETED - TRAINING_OPERATION_STATUS_FAILED default: TRAINING_OPERATION_STATUS_UNSPECIFIED RL.ForwardBackwardResult: type: object description: Result of a scored forward or forward-backward operation required: - loss properties: loss: type: number example: 2.345 description: Loss value metrics: type: object description: Loss-specific metrics (e.g., KL divergence, clip fraction for GRPO) example: loss/clip/high_fraction: 0.1 loss/kl_ref/mean: 0.05 additionalProperties: type: number loss_fn_outputs: type: array description: >- Per-sample loss function outputs, in request order. Empty unless the request set `return_loss_fn_outputs`. items: $ref: '#/components/schemas/RL.LossFnOutput' RL.TrainingOperationError: type: object description: Error details for a failed training operation properties: code: $ref: '#/components/schemas/RL.TrainingOperationErrorCode' description: Application error code example: TRAINING_OPERATION_ERROR_CODE_TIMEOUT message: description: Human-readable error message type: string example: Operation timed out RL.ModelInput: type: object required: - chunks properties: chunks: description: Input chunks for the model type: array items: $ref: '#/components/schemas/RL.ModelInputChunk' type: object RL.TensorData: type: object description: A tensor encoded as flattened row-major values, with an optional shape. required: - data - dtype properties: data: type: array description: Flattened one-dimensional values encoded as JSON numbers. example: - 1 - 2 - 3 items: type: number format: double dtype: type: string enum: - int64 - float32 description: Tensor element type, either `int64` or `float32`. example: int64 shape: type: array description: >- Optional tensor shape; training operations accept one-dimensional tensors only, and the dimension must match the data length. example: - 3 items: type: integer sparse_crow_indices: type: array description: Unsupported for training operations. Omit this field. example: - 0 - 2 items: type: integer sparse_col_indices: type: array description: Unsupported for training operations. Omit this field. example: - 0 - 2 items: type: integer RL.LossType: type: string description: Type of loss function used for RL training. enum: - LOSS_TYPE_UNSPECIFIED - LOSS_TYPE_CROSS_ENTROPY - LOSS_TYPE_GRPO - LOSS_TYPE_IMPORTANCE_SAMPLING - LOSS_TYPE_PPO - LOSS_TYPE_CISPO - LOSS_TYPE_DRO - LOSS_TYPE_DPPO default: LOSS_TYPE_UNSPECIFIED RL.CrossEntropyLossParams: type: object description: Cross-entropy loss parameters (currently empty). properties: {} additionalProperties: false x-stainless-empty-object: true RL.GRPOLossParams: type: object properties: clip_low_threshold: type: number format: float example: 0.8 default: 0.8 description: >- Lower clip threshold for the importance-sampling ratio. The ratio is clamped to this bound; tighter clipping makes policy updates more conservative. Must be <= 1. clip_high_threshold: type: number format: float example: 1.2 default: 1.2 description: >- Upper clip threshold for the importance-sampling ratio. The ratio is clamped to this bound; tighter clipping makes policy updates more conservative. Must be >= 1. beta: type: number example: 0.1 default: 0 description: KL penalty coefficient agg_type: $ref: '#/components/schemas/RL.GRPOLossAggregationType' example: GRPO_LOSS_AGGREGATION_TYPE_FIXED_HORIZON default: GRPO_LOSS_AGGREGATION_TYPE_FIXED_HORIZON description: Aggregation type for loss computation ratio_type: $ref: '#/components/schemas/RL.GRPOLossRatioType' example: GRPO_LOSS_RATIO_TYPE_TOKEN default: GRPO_LOSS_RATIO_TYPE_TOKEN description: >- Controls how the importance-sampling ratio is computed in GRPO loss. Defaults to token-level ratios, which is the standard GRPO behavior. Use sequence-level ratios to enable GSPO-style loss calculation instead. RL.PPOLossParams: type: object properties: clip_low_threshold: type: number format: float example: 0.8 default: 0.8 description: >- Lower absolute bound for the importance ratio in the clipped surrogate. Must be <= 1. clip_high_threshold: type: number format: float example: 1.2 default: 1.2 description: >- Upper absolute bound for the importance ratio in the clipped surrogate. Must be >= 1. RL.CISPOLossParams: type: object properties: clip_low_threshold: type: number format: float example: 0 default: 0 description: Lower bound for clipping the importance-sampling ratio. clip_high_threshold: type: number format: float example: 4 default: 4 description: Upper bound for clipping the importance-sampling ratio. RL.DROLossParams: type: object properties: beta: type: number format: float example: 0.05 description: >- Coefficient on the quadratic log-ratio penalty. Required; there is no default. required: - beta RL.DPPOLossParams: type: object properties: delta_low: type: number format: float example: 0.15 default: 0.15 description: >- Probability-change limit for tokens with negative advantage. Measured in probability space, not log-probability space. Must be in [0, 1]. Defaults to 0.15. minimum: 0 maximum: 1 delta_high: type: number format: float example: 0.15 default: 0.15 description: >- Probability-change limit for tokens with positive advantage. Measured in probability space, not log-probability space. Must be in [0, 1]. Defaults to 0.15. minimum: 0 maximum: 1 description: >- Parameters for DPPO loss. Both probability-change limits must be in [0, 1] and default to 0.15. RL.LossFnOutput: type: object description: Output tensors produced by the loss function for one sample. required: - tensors properties: tensors: type: object description: >- Output tensors keyed by name. Built-in losses return `logprobs`: the model's float32 per-token log-probabilities under the current policy, one value per token of the sample's input. Positions excluded from the loss, such as zero-weight positions, are masked to zero rather than true log-probabilities. additionalProperties: $ref: '#/components/schemas/RL.TensorData' RL.TrainingOperationErrorCode: type: string description: Application error code for a failed training operation enum: - TRAINING_OPERATION_ERROR_CODE_UNSPECIFIED - TRAINING_OPERATION_ERROR_CODE_RESOURCE_EXHAUSTED - TRAINING_OPERATION_ERROR_CODE_TIMEOUT - TRAINING_OPERATION_ERROR_CODE_INTERNAL_ERROR - TRAINING_OPERATION_ERROR_CODE_SESSION_NOT_ACTIVE - TRAINING_OPERATION_ERROR_CODE_INVALID_INPUT - TRAINING_OPERATION_ERROR_CODE_NON_FINITE_LOSS default: TRAINING_OPERATION_ERROR_CODE_UNSPECIFIED RL.ModelInputChunk: type: object description: A single chunk of model input content. required: - encoded_text properties: encoded_text: $ref: '#/components/schemas/RL.EncodedTextChunk' description: Pre-tokenized text content for this input chunk. RL.GRPOLossAggregationType: type: string enum: - GRPO_LOSS_AGGREGATION_TYPE_UNSPECIFIED - GRPO_LOSS_AGGREGATION_TYPE_FIXED_HORIZON - GRPO_LOSS_AGGREGATION_TYPE_TOKEN_MEAN - GRPO_LOSS_AGGREGATION_TYPE_SEQUENCE_MEAN default: GRPO_LOSS_AGGREGATION_TYPE_UNSPECIFIED RL.GRPOLossRatioType: type: string description: >- Controls whether GRPO loss uses token-level or sequence-level importance ratios. enum: - GRPO_LOSS_RATIO_TYPE_TOKEN - GRPO_LOSS_RATIO_TYPE_SEQUENCE default: GRPO_LOSS_RATIO_TYPE_TOKEN RL.EncodedTextChunk: type: object description: Pre-tokenized text content for a model input chunk. required: - tokens properties: tokens: description: Pre-tokenized text input type: array example: - 123 - 456 - 789 items: oneOf: - type: string - type: integer securitySchemes: bearerAuth: type: http scheme: bearer x-bearer-format: bearer x-default: default ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.