> ## 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. # Sample > Submits a sample operation that will asynchronously generate text completions with logprobs. ## OpenAPI ````yaml openapi.yaml POST /rl/training-sessions/{session_id}/operations/sample 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/sample: post: tags: - RL summary: Sample description: >- Submits a sample operation that will asynchronously generate text completions with logprobs. operationId: Sample 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.SampleBody' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RL.SampleOperation' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/ErrorData' components: schemas: RL.SampleBody: type: object required: - model_inputs properties: model_inputs: description: Model inputs to sample from type: array items: $ref: '#/components/schemas/RL.ModelInput' type: object sampling_params: $ref: '#/components/schemas/RL.SamplingParams' description: Optional sampling parameters num_samples: type: integer example: 1 default: 1 description: Number of completions to generate per prompt prompt_logprobs: type: boolean example: false default: false description: >- When true, also compute teacher-forced log-probabilities for the model input tokens and return them in `SampleResult.prompt_logprobs`. topk_prompt_logprobs: type: integer minimum: 0 maximum: 20 example: 0 default: 0 description: >- Number of most likely alternative tokens to return per model input token in `SampleResult.topk_prompt_logprobs`. 0 disables top-k prompt log-probabilities. Maximum 20. return_routed_experts: type: boolean example: false default: false description: >- When true, enable reuse of the expert selections from sampled sequences during training. Only supported for mixture-of-experts models; ignored for other models. RL.SampleOperation: type: object description: Async sample 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.SampleBatchResult' 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.ModelInput: type: object required: - chunks properties: chunks: description: Input chunks for the model type: array items: $ref: '#/components/schemas/RL.ModelInputChunk' type: object RL.SamplingParams: type: object properties: max_tokens: type: integer example: 512 default: 512 description: Maximum number of tokens to generate per completion temperature: type: number example: 1 default: 1 description: Sampling temperature top_p: type: number example: 1 default: 1 description: Nucleus sampling probability threshold top_k: type: integer example: -1 default: -1 description: Top-k sampling limit stop: type: array example: - |+ - END items: type: string description: Generation stops when any of these strings is produced seed: oneOf: - type: string - type: integer example: '42' description: >- Random seed for reproducible sampling for the same prompt and model state. 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.SampleBatchResult: type: object description: Batched result of a sample operation required: - results properties: results: type: array items: $ref: '#/components/schemas/RL.SampleResult' type: object description: One result per model input 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.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.SampleResult: type: object description: Completions generated for a single model input required: - sequences - policy_segments properties: sequences: type: array items: $ref: '#/components/schemas/RL.SampledSequence' type: object description: Generated completions prompt_logprobs: type: array example: - 0 - -0.5 - -1.2 items: type: number format: double description: >- Teacher-forced log-probability of each model input token. Full prompt length; entry i corresponds to prompt token i. Entry 0 is always 0 as a placeholder: the first prompt token has no conditioning context, so it has no log-probability. Present only when prompt_logprobs was set on the request. topk_prompt_logprobs: type: array items: $ref: '#/components/schemas/RL.PromptTopLogprobs' type: object description: >- The most likely alternative tokens at each model input token, up to `topk_prompt_logprobs` per position. Full prompt length; entry i corresponds to prompt token i, and entry 0 is empty. Present only when topk_prompt_logprobs was set on the request. policy_segments: type: array items: $ref: '#/components/schemas/RL.PolicyVersionSegment' type: object description: Policy versions that produced these completions 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.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 RL.SampledSequence: type: object description: A single generated completion sequence with tokens and logprobs required: - tokens - stop_reason - prompt_cache_hit_tokens properties: tokens: type: array example: - '123' - '456' - '789' items: oneOf: - type: string - type: integer description: Generated token IDs logprobs: type: array example: - -0.5 - -1.2 - -0.3 items: type: number description: Log probabilities for each generated token stop_reason: $ref: '#/components/schemas/RL.StopReason' example: STOP_REASON_LENGTH description: Reason for stopping generation prompt_cache_hit_tokens: type: integer format: int32 example: 1024 description: >- Number of model input tokens served from the prefix cache while generating this sequence. routed_experts_key: type: string description: >- Opaque key for reusing this sequence's expert selections during training. Pass it unchanged with the corresponding training sample. Absent for non-mixture-of-experts models or when `return_routed_experts` is disabled. RL.PromptTopLogprobs: type: object description: >- The most likely alternative tokens at a single prompt position, as two parallel arrays of equal length. Both are empty for a position with no conditioning context, such as position 0. properties: token_ids: type: array example: - 123 - 456 items: type: integer format: int32 description: >- Token IDs of the alternatives, ordered by descending log-probability. logprobs: type: array example: - -0.5 - -2.1 items: type: number format: double description: >- Log-probability of each alternative in `token_ids`, at the same index. RL.PolicyVersionSegment: type: object description: >- A (policy version, starting token) span within a sampled sequence. Version 0 is the initial model; each optim_step call increments the version by 1. required: - version - start_token properties: version: type: integer format: int32 example: 5 description: Model version under which this segment of tokens was generated start_token: type: integer format: int32 example: 0 description: >- Index of the first token of this segment within the sampled sequence. Always 0 for the first segment. RL.StopReason: type: string description: Reason generation stopped. enum: - STOP_REASON_LENGTH - STOP_REASON_STOP 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.