--- title: "Estimate rollout time and price" method: POST path: "/v1/rl/rollouts/estimate" tags: ["RL"] --- # Estimate rollout time and price `POST /v1/rl/rollouts/estimate` ## Request - Base URL: `https://api.together.ai` - URL: `https://api.together.ai/v1/rl/rollouts/estimate` - Auth: HTTP bearer Estimates rollout-only time, generator GPU-hours, billed GPU-hours of the whole model resource, and price for a supported model and GPU type. Each generator replica may contain several inference servers or span multiple nodes. Assumes identical episodes, exact reuse of generated tokens between turns, turns that start together within a replica, no environment delay, and no concurrent computation of the same initial prompt. Prompt-cache reuse and capacity misses are approximate, especially for multi-turn episodes. Rates are measured in the training mode reported by lora_enabled. Cache-transfer and request-preemption delays are not included, so long multi-turn rollouts with distinct prompts can take longer than estimated. ## Request body - RLEstimateRolloutRequest: Episode shape, model, GPU type, and concurrency for a rollout-only estimate - `episodes` integer, required: Total number of episodes (N). Must be between 1 and 10000000. - `concurrency` integer, required: Maximum concurrent episodes across all generator replicas (B). Must be positive. - `prompt_tokens` integer, required: Initial prompt tokens per episode (P). Must be positive. - `turns` integer, required: Assistant turns per episode (T). Must be between 1 and 1024. - `added_tokens_per_turn` integer, required: Tokens added before each later turn (K), including the prior generated tokens followed by environment tokens. Must be at least generated_tokens_per_turn. - `generated_tokens_per_turn` integer, required: Tokens generated on each turn (O). Must be positive. - `distinct_prompts_per_replica` integer: Number of distinct initial prompts among the concurrent episodes of one replica (Q). When episodes_per_prompt is given, defaults to ceil(concurrent episodes / G). Otherwise defaults to 1 when shared_prefix_tokens equals prompt_tokens, and to the concurrent episodes per replica when it does not. Must be 1 when shared_prefix_tokens equals prompt_tokens. - `episodes_per_prompt` integer: Maximum sibling episodes per initial prompt (G). When distinct_prompts_per_replica is given, defaults to ceil(concurrent episodes / Q). Otherwise defaults to the concurrent episodes per replica when shared_prefix_tokens equals prompt_tokens, and to 1 when it does not. When shared_prefix_tokens equals prompt_tokens, must be at least the concurrent episodes per replica. - `shared_prefix_tokens` integer: Leading tokens shared by all distinct initial prompts (H). Defaults to 0; cannot exceed prompt_tokens. - `base_model` string, required: Base model to estimate. The model, GPU type, and training mode must support rollout estimates. - `compute_config` RLComputeConfigCreateRequest: Compute layout to provision for a model resource - `num_generator_replicas` integer: Number of generator replicas. 0 runs the trainer only, with no generator. - `gpu_type` 'B200-SXM': GPU type to provision. Omit to use the model's default GPU type. - `num_trainer_replicas` integer: Number of trainers: 0 or 1. Omit to use 1. Each trainer can use multiple GPUs. With 0, at least one generator replica is required, optimizer_config is not allowed, and sessions must resume from an inference checkpoint for sampling only. - `lora_enabled` boolean: Whether to estimate a resource that hosts LoRA sessions (true, default) or a single full-weight session (false), as in a model resource. The model and GPU type must support rollout estimates in this mode. ## Response `200` Estimated rollout time and price - RLEstimateRolloutResponse: Estimated rollout elapsed time, tokens, throughput, GPU-hours, and price - `wall_seconds` number, double, required: Estimated time until all rollout episodes finish, in seconds. - `allocated_gpu_hours` number, double, required: Generator GPUs across all replicas times wall time, in GPU-hours. - `submitted_prompt_tokens` union, required: Prompt tokens submitted across all turns. JSON encodes this count as a decimal string. - string - integer - `generated_tokens` union, required: Generated output tokens across all turns. JSON encodes this count as a decimal string. - string - integer - `effective_decode_tokens_per_second` number, double, required: generated_tokens divided by wall_seconds. - `effective_distinct_prompts_per_replica` integer, required: Effective distinct_prompts_per_replica (Q) for the largest concurrent batch of one replica. - `effective_episodes_per_prompt` integer, required: Effective episodes_per_prompt (G) for the largest concurrent batch of one replica. - `effective_shared_prefix_tokens` integer, required: Effective shared_prefix_tokens (H). - `lora_enabled` boolean, required: Whether the estimate is for a LoRA resource (true) or a full-weight resource (false). - `billed_gpu_hours` number, double, required: GPUs of the whole model resource, trainer and generator, times wall time, in GPU-hours. A model resource is billed for all of its GPUs while the rollouts run. An approximation measured on single-wave rollouts (concurrency equal to episodes) of up to four turns on one generator replica: actual usage can be up to about 45% higher when episodes share a prompt, and about 20% higher or lower otherwise. Longer multi-turn rollouts with distinct prompts can take longer than estimated. - `estimated_price` number, double, required: Estimated on-demand price of the rollouts: billed_gpu_hours times the GPU type's list price per GPU-hour, the rate the model resource cost estimate uses. An approximation that inherits the uncertainty of billed_gpu_hours; it is not a quote. - `currency` string, required: Currency of estimated_price. - `effective_prefill_tokens_per_second` number, double, required: submitted_prompt_tokens divided by wall_seconds, counting prompt tokens served from the prompt cache. ## Other responses - `default`: An unexpected error response. ## Changes - **2026-11-13** `5e76d8b23bff`: 1 info - endpoint added [Operation history](https://skmtc.dev/together/apis/together-apis/changes/v1/rl/rollouts/estimate/post.md) --- [API](https://skmtc.dev/together/apis/together-apis.md) - [All operations](https://skmtc.dev/together/apis/together-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/together/apis/together-apis/revisions/5e76d8b23bff?raw)