> ## Documentation Index > Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a Scenario. > Get a previously created scenario. ## OpenAPI ````yaml /openapi-specs/stainless-processed-openapi.json get /v1/scenarios/{id} openapi: 3.1.0 info: title: RunLoop API version: '0.1' description: >- The RunLoop API spec that allows you to host lambda functions and Devboxes to enable scaled long running ai workflows. contact: name: Runloop AI Support url: https://runloop.ai email: support@runloop.ai servers: - url: https://api.runloop.ai description: Runloop API variables: {} security: - bearerAuth: [] tags: - name: Benchmark - name: Blueprint - name: Blueprint-Lifecycle - name: Blueprint-ObservabilityTools - name: Devbox - name: Devbox-FileTools - name: Devbox-Lifecycle - name: Devbox-NetworkTools - name: Devbox-ObservabilityTools - name: Devbox-PersistenceTools - name: Devbox-ShellTools - name: Scenario - name: ScenarioScorer - name: accounts - name: agents - name: apikeys - name: axons - name: executions - name: gateway-configs - name: mcp-configs - name: network-policies - name: objects - name: restricted_keys - name: secrets - name: streaming paths: /v1/scenarios/{id}: get: tags: - Scenario summary: Get a Scenario. description: Get a previously created scenario. operationId: getScenario parameters: - name: id in: path description: The Scenario ID. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ScenarioDefinitionView' x-codeSamples: - lang: JavaScript source: |- import Runloop from '@runloop/api-client'; const client = new Runloop({ bearerToken: process.env['RUNLOOP_API_KEY'], // This is the default and can be omitted }); const scenarioView = await client.scenarios.retrieve('id'); console.log(scenarioView.id); - lang: Python source: |- import os from runloop_api_client import Runloop client = Runloop( bearer_token=os.environ.get("RUNLOOP_API_KEY"), # This is the default and can be omitted ) scenario_view = client.scenarios.retrieve( "id", ) print(scenario_view.id) components: schemas: ScenarioDefinitionView: type: object description: >- A ScenarioDefinitionView represents a repeatable AI coding evaluation test, complete with initial environment and scoring contract. properties: id: type: string description: The ID of the Scenario. name: type: string description: The name of the Scenario. environment: description: The Environment in which the Scenario is run. anyOf: - $ref: '#/components/schemas/ScenarioEnvironment' - type: 'null' input_context: $ref: '#/components/schemas/InputContext' description: The input context for the Scenario. scoring_contract: $ref: '#/components/schemas/ScoringContract' description: The scoring contract for the Scenario. metadata: type: object additionalProperties: type: string description: User defined metadata to attach to the scenario for organization. reference_output: description: >- A string representation of the reference output to solve the scenario. Commonly can be the result of a git diff or a sequence of command actions to apply to the environment. type: - string - 'null' required_environment_variables: type: array items: type: string description: >- Environment variables required to run the scenario. If any required environment variables are missing, the scenario will fail to start. required_secret_names: type: array items: type: string description: >- Environment variables required to run the scenario. If any required secrets are missing, the scenario will fail to start. is_public: type: boolean description: Whether this scenario is public. validation_type: description: Validation strategy. anyOf: - $ref: '#/components/schemas/ValidationType' - type: 'null' scorer_timeout_sec: format: int32 description: Timeout for scoring in seconds. Default 30 minutes (1800s). type: - integer - 'null' status: $ref: '#/components/schemas/ScenarioDefinitionStatus' description: >- Whether the scenario is active or archived. Archived scenarios are excluded from listings and cannot be updated. required: - id - name - input_context - scoring_contract - metadata - status ScenarioEnvironment: type: object description: >- ScenarioEnvironmentParameters specify the environment in which a Scenario will be run. properties: blueprint_id: description: Use the blueprint with matching ID. type: - string - 'null' snapshot_id: description: Use the snapshot with matching ID. type: - string - 'null' launch_parameters: description: >- Optional launch parameters to apply to the devbox environment at launch. anyOf: - $ref: '#/components/schemas/LaunchParameters' - type: 'null' working_directory: description: >- The working directory where the agent is expected to fulfill the scenario. Scoring functions also run from the working directory. type: - string - 'null' InputContext: type: object description: >- InputContextView specifies the problem statement along with all additional context for a Scenario. properties: problem_statement: type: string description: The problem statement for the Scenario. additional_context: description: Additional JSON structured input context. type: - object - 'null' required: - problem_statement ScoringContract: type: object description: >- InputContextView specifies the problem statement along with all additional context for a Scenario. properties: scoring_function_parameters: type: array items: $ref: '#/components/schemas/ScoringFunction' description: A list of scoring functions used to evaluate the Scenario. required: - scoring_function_parameters ValidationType: type: string enum: - UNSPECIFIED - FORWARD - REVERSE - EVALUATION ScenarioDefinitionStatus: type: string enum: - active - archived LaunchParameters: type: object description: >- LaunchParameters enable you to customize the resources available to your Devbox as well as the environment set up that should be completed before the Devbox is marked as 'running'. properties: launch_commands: items: type: string description: >- Set of commands to be run at launch time, before the entrypoint process is run. type: - array - 'null' resource_size_request: description: >- Preset Devbox resources (vCPU, RAM in GiB, ephemeral disk in GiB). If not set, SMALL is used. X_SMALL: 0.5 vCPU, 1 GiB RAM, 4 GiB disk. SMALL: 1 vCPU, 2 GiB RAM, 4 GiB disk. MEDIUM: 2 vCPU, 4 GiB RAM, 8 GiB disk. LARGE: 2 vCPU, 8 GiB RAM, 16 GiB disk. X_LARGE: 4 vCPU, 16 GiB RAM, 16 GiB disk. XX_LARGE: 8 vCPU, 32 GiB RAM, 16 GiB disk. CUSTOM_SIZE: set custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size. anyOf: - $ref: '#/components/schemas/ResourceSize' - type: 'null' available_ports: items: type: integer format: int32 description: >- [Deprecated] A list of ports to make available on the Devbox. This field is ignored. type: - array - 'null' keep_alive_time_seconds: format: int64 description: >- Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds). type: - integer - 'null' after_idle: description: >- Configure Devbox lifecycle based on idle activity. If after_idle is set, Devbox will ignore keep_alive_time_seconds. If both after_idle and lifecycle.after_idle are set, they must have the same value. Use lifecycle.after_idle instead. anyOf: - $ref: '#/components/schemas/IdleConfigurationParameters' - type: 'null' custom_cpu_cores: format: int32 description: Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16. type: - integer - 'null' custom_gb_memory: format: int32 description: >- Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB. type: - integer - 'null' custom_disk_size: format: int32 description: >- Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB. type: - integer - 'null' architecture: description: >- The target architecture for the Devbox. If unset, defaults to x86_64. anyOf: - $ref: '#/components/schemas/Architecture' - type: 'null' user_parameters: description: >- Specify the user for execution on Devbox. If not set, default `user` will be used. anyOf: - $ref: '#/components/schemas/UserParameters' - type: 'null' required_services: items: type: string description: >- A list of ContainerizedService names to be started when a Devbox is created. A valid ContainerizedService must be specified in Blueprint to be started. type: - array - 'null' network_policy_id: description: >- (Optional) ID of the network policy to apply to Devboxes launched with these parameters. When set on a Blueprint launch parameters, Devboxes created from it will inherit this policy unless explicitly overridden. type: - string - 'null' lifecycle: description: >- Lifecycle configuration for idle and resume behavior. Configure idle policy via lifecycle.after_idle (if both this and the top-level after_idle are set, they must match), resume triggers via lifecycle.resume_triggers, and optional lifecycle hooks via lifecycle.lifecycle_hooks. anyOf: - $ref: '#/components/schemas/LifecycleConfigurationParameters' - type: 'null' provisioning_tier: description: >- (Optional, Alpha) standard is default and flex is lazily provisioned and may be pre-empted. This is an alpha feature and its behavior may change without notice. anyOf: - $ref: '#/components/schemas/ProvisioningTier' - type: 'null' ScoringFunction: type: object description: ScoringFunction specifies a method of scoring a Scenario. properties: name: type: string description: Name of scoring function. Names must only contain [a-zA-Z0-9_-]. scorer: $ref: '#/components/schemas/BuiltInScoringFunction' description: >- The scoring function to use for evaluating this scenario. The type field determines which built-in function to use. weight: type: number format: float description: >- Weight to apply to scoring function score. Weights of all scoring functions should sum to 1.0. required: - name - scorer - weight ResourceSize: type: string enum: - X_SMALL - SMALL - MEDIUM - LARGE - X_LARGE - XX_LARGE - CUSTOM_SIZE description: > The size of the Devbox resources for Runloop to allocate. X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk SMALL: 1 cpu x 2GiB memory x 4GiB disk MEDIUM: 2 cpu x 4GiB memory x 8GiB disk LARGE: 2 cpu x 8GiB memory x 16GiB disk X_LARGE: 4 cpu x 16GiB memory x 16GiB disk XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk CUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive. x-enum-descriptions: X_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk SMALL: 1 cpu x 2GiB memory x 4GiB disk MEDIUM: 2 cpu x 4GiB memory x 8GiB disk LARGE: 2 cpu x 8GiB memory x 16GiB disk X_LARGE: 4 cpu x 16GiB memory x 16GiB disk XX_LARGE: 8 cpu x 32GiB memory x 16GiB disk CUSTOM_SIZE: >- To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive. IdleConfigurationParameters: type: object properties: idle_time_seconds: type: integer format: int32 description: After idle_time_seconds, on_idle action will be taken. on_idle: $ref: '#/components/schemas/IdleAction' description: Action to take after Devbox becomes idle. required: - idle_time_seconds - on_idle Architecture: type: string enum: - x86_64 - arm64 UserParameters: type: object description: Configuration for the Linux user in the Devbox environment. properties: username: type: string description: Username for the Linux user. uid: type: integer format: int32 description: User ID (UID) for the Linux user. Must be a non-negative integer. required: - username - uid LifecycleConfigurationParameters: type: object description: >- Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle, resume triggers via resume_triggers, and optional lifecycle hooks via lifecycle_hooks. properties: after_idle: description: >- Configure Devbox lifecycle based on idle activity. If both this and the top-level after_idle are set, they must have the same value. Prefer this field for new integrations. anyOf: - $ref: '#/components/schemas/IdleConfigurationParameters' - type: 'null' resume_triggers: description: Triggers that can resume a suspended Devbox. anyOf: - $ref: '#/components/schemas/ResumeTriggers' - type: 'null' lifecycle_hooks: description: >- Optional lifecycle hooks. suspend_commands run through the suspend path before the Devbox suspends; see launch_commands for work on every startup. anyOf: - $ref: '#/components/schemas/LifecycleHooks' - type: 'null' ProvisioningTier: type: string enum: - standard - flex BuiltInScoringFunction: oneOf: - $ref: '#/components/schemas/AstGrepScoringFunction' - $ref: '#/components/schemas/BashScriptScoringFunction' - $ref: '#/components/schemas/CommandScoringFunction' - $ref: '#/components/schemas/CustomScoringFunction' - $ref: '#/components/schemas/PythonScriptScoringFunction' - $ref: '#/components/schemas/TestBasedScoringFunction' discriminator: propertyName: type mapping: ast_grep_scorer: $ref: '#/components/schemas/AstGrepScoringFunction' bash_script_scorer: $ref: '#/components/schemas/BashScriptScoringFunction' command_scorer: $ref: '#/components/schemas/CommandScoringFunction' custom_scorer: $ref: '#/components/schemas/CustomScoringFunction' python_script_scorer: $ref: '#/components/schemas/PythonScriptScoringFunction' test_based_scorer: $ref: '#/components/schemas/TestBasedScoringFunction' IdleAction: type: string enum: - shutdown - suspend description: | Action to take after Devbox idle timer is triggered. shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. x-enum-descriptions: shutdown: Shutdown the Devbox. suspend: Suspend the Devbox. ResumeTriggers: type: object description: Triggers that can resume a suspended Devbox. properties: http: description: >- When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume. type: - boolean - 'null' axon_event: description: >- When true, axon events targeting a suspended Devbox will trigger a resume. type: - boolean - 'null' LifecycleHooks: type: object description: >- Lifecycle hooks for Devbox suspend. suspend_commands run sequentially as the configured Devbox user before the Devbox suspends; failures are logged but do not block suspending. The suspend_deadline_ms budget defaults to 30000 ms, may not exceed 60000 ms, and covers broker drain plus suspend_commands. If the deadline is exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend. launch_commands still run on every startup, including after resume. properties: suspend_commands: items: type: string description: >- Commands to run through the suspend path before the Devbox suspends (e.g. cleanup, quiesce daemons). type: - array - 'null' suspend_deadline_ms: format: int64 description: >- Deadline in milliseconds for broker drain and suspend_commands during suspend. Defaults to 30000 ms and may not exceed 60000 ms. If exceeded, suspend work is abandoned, the timeout is logged, and the Devbox still proceeds to suspend by shutting down vmagent and killing the VM. type: - integer - 'null' AstGrepScoringFunction: type: object description: AstGrepScoringFunction utilizes structured coach search for scoring. properties: lang: type: string description: The language of the pattern. search_directory: type: string description: The path to search. pattern: type: string description: >- AST pattern to match. Pattern will be passed to ast-grep using the commandline surround by double quotes ("), so make sure to use proper escaping (for example, \$\$\$). type: type: string enum: - ast_grep_scorer default: ast_grep_scorer required: - search_directory - pattern - type BashScriptScoringFunction: type: object description: >- BashScriptScoringFunction is a scoring function specified by a bash script that will be run in the context of your environment. properties: bash_script: type: string description: >- A single bash script that sets up the environment, scores, and prints the final score to standard out. Score should be a float between 0.0 and 1.0, and look like "score=[0.0..1.0]. type: type: string enum: - bash_script_scorer default: bash_script_scorer required: - type CommandScoringFunction: type: object description: >- CommandScoringFunction executes a single command and checks the result.The output of the command will be printed. Scoring will passed if the command returns status code 0, otherwise it will be failed. properties: command: type: string description: The command to execute. type: type: string enum: - command_scorer default: command_scorer required: - type CustomScoringFunction: type: object description: CustomScoringFunction is a custom, user defined scoring function. properties: custom_scorer_type: type: string description: Type of the scoring function, previously registered with Runloop. scorer_params: description: Additional JSON structured context to pass to the scoring function. type: - object - 'null' type: type: string enum: - custom_scorer default: custom_scorer required: - custom_scorer_type - type PythonScriptScoringFunction: type: object description: >- PythonScriptScoringFunction will run a python script in the context of your environment as a ScoringFunction. properties: requirements_contents: description: >- Package dependencies to be installed. The requirements should be a valid requirements.txt file. type: - string - 'null' python_script: type: string description: >- Python script to be run. The script should output the score to standard out as a float between 0.0 and 1.0. python_version_constraint: description: Python version to run scoring. Default is "==3.12.10" type: - string - 'null' type: type: string enum: - python_script_scorer default: python_script_scorer required: - python_script - type TestBasedScoringFunction: type: object description: >- TestBasedScoringFunction writes test files to disk and executes a test command to verify the solution. properties: test_files: type: array items: $ref: '#/components/schemas/TestFile' description: List of test files to create test_command: type: string description: The command to execute for running the tests type: type: string enum: - test_based_scorer default: test_based_scorer required: - type TestFile: type: object properties: file_path: type: string description: >- Path to write content of the test file, relative to your environment's working directory file_contents: type: string description: Content of the test file securitySchemes: bearerAuth: scheme: bearer type: http ````