RunRL

API Reference

Detailed documentation of the RunRL Python client API

API Reference

This page provides detailed documentation for all methods available in the RunRL Python client.

Client Initialization

from runrl import RunRL

client = RunRL(
    api_key="rl-your-api-key",
    base_url="https://runrlusercontent.com"  # Optional, defaults to this URL
)

Parameters

  • api_key (str, required): Your RunRL API key
  • base_url (str, optional): The base URL for the RunRL API. Defaults to "https://runrlusercontent.com"

User Data

get_user_data()

Retrieves information about the authenticated user.

user_data = client.get_user_data()

Returns: A dictionary containing user information.

Runs

list_runs()

Lists all runs for the authenticated user.

runs = client.list_runs()

Returns: A list of dictionaries, each containing information about a run.

create_run()

Creates a new run with the specified parameters.

run = client.create_run(
    model_name="Qwen/Qwen3-4B",
    prompt_file="file-123",
    reward_file="file-456",
    gpu_type="H100",
    n_gpus=8,
    lora_rank=0,
    max_seq_length=1024,
    epochs=1,
    learning_rate=5e-6,
    turbo=True
)

Parameters:

  • model_name (str, required): The name of the model
  • prompt_file (str, required): ID of the uploaded prompt file
  • reward_file (str, required): ID of the uploaded reward file

Hyperparameters:

  • learning_rate (float, optional): Controls the step size for updating model weights. Smaller values lead to slower but potentially more stable learning. In GRPO (Generative Reinforcement Learning with Proximal Optimization), it affects how quickly the agent's policy adapts. Defaults to 5e-6.

  • weight_decay (float, optional): A regularization technique that penalizes large weights, helping to prevent overfitting and improve the model's generalization.

  • adam_beta1 (float, optional): The exponential decay rate for the first moment estimates (mean of gradients) in the Adam optimizer. Typically around 0.9.

  • adam_beta2 (float, optional): The exponential decay rate for the second moment estimates (variance of gradients) in the Adam optimizer. Typically around 0.999.

  • warmup_ratio (float, optional): Fraction of total training steps for a learning rate warmup, where the learning rate gradually increases. Helps stabilize training early on.

  • kl_beta (float, optional): Coefficient for the KL divergence penalty. It controls how much the policy can change in one update, ensuring stability. Setting this to 0.0 will significantly reduce memory requirements.

Configuration Parameters:

  • lora_rank (int, optional): The rank of the Low-Rank Adaptation matrices. Higher values allow for more expressive parameter updates but require more memory and computation. A value of 0 means LoRA is not used. Defaults to 0.

  • max_seq_length (int, optional): The maximum length of input sequences. Longer sequences provide more context but require more memory and computation. Defaults to 1024.

  • epochs (int, optional): The number of complete passes through the training dataset. Defaults to 1.

  • gpu_type (str, optional): The type of GPU to use for training. Options include "H100", "A100", etc. Defaults to "H100".

  • n_gpus (int, optional): The number of GPUs to use for training. Defaults to 8.

  • turbo (bool, optional): When enabled, uses a specific configuration optimized for speed (requires H100 GPUs and n_gpus=8). Defaults to True.

  • hf_token (str, optional): Hugging Face token for accessing gated models.

Returns: A dictionary containing information about the created run.

Note: When turbo=True, gpu_type must be "H100" and n_gpus must be 8.

get_run_details(run_id)

Gets detailed information about a specific run.

run_details = client.get_run_details("run-123")

Parameters:

  • run_id (str, required): The ID of the run

Returns: A dictionary containing detailed information about the run.

cancel_run(run_id)

Cancels a running job.

result = client.cancel_run("run-123")

Parameters:

  • run_id (str, required): The ID of the run to cancel

Returns: A dictionary containing the result of the cancellation.

Prompt Files

For details on prompt file format requirements, see the File Formats documentation.

list_prompt_files()

Lists all prompt files for the authenticated user.

prompt_files = client.list_prompt_files()

Returns: A list of dictionaries, each containing information about a prompt file.

upload_prompt_file(file_path, friendly_name=None)

Uploads a new prompt file.

prompt_file = client.upload_prompt_file(
    file_path="path/to/prompt.jsonl",
    friendly_name="My Prompt File"  # Optional
)

Parameters:

  • file_path (str, required): Path to the file to upload
  • friendly_name (str, optional): A user-friendly name for the file

Returns: A dictionary containing information about the uploaded file.

delete_prompt_file(file_id)

Deletes a prompt file.

result = client.delete_prompt_file("file-123")

Parameters:

  • file_id (str, required): The ID of the file to delete

Returns: A dictionary containing the result of the deletion.

get_prompt_file_preview(file_id)

Gets a preview of a prompt file.

preview = client.get_prompt_file_preview("file-123")

Parameters:

  • file_id (str, required): The ID of the file to preview

Returns: A dictionary containing the file preview.

Reward Files

For details on reward function format requirements, see the File Formats documentation.

list_reward_files()

Lists all reward files for the authenticated user.

reward_files = client.list_reward_files()

Returns: A list of dictionaries, each containing information about a reward file.

upload_reward_file(file_path, friendly_name=None)

Uploads a new reward file.

reward_file = client.upload_reward_file(
    file_path="path/to/reward.jsonl",
    friendly_name="My Reward File"  # Optional
)

Parameters:

  • file_path (str, required): Path to the file to upload
  • friendly_name (str, optional): A user-friendly name for the file

Returns: A dictionary containing information about the uploaded file.

delete_reward_file(file_id)

Deletes a reward file.

result = client.delete_reward_file("file-123")

Parameters:

  • file_id (str, required): The ID of the file to delete

Returns: A dictionary containing the result of the deletion.

get_reward_file_content(file_id)

Gets the content of a reward file.

content = client.get_reward_file_content("file-123")

Parameters:

  • file_id (str, required): The ID of the file to get content for

Returns: A dictionary containing the file content.

Models & Deployments

download_model(job_name, output_path)

Downloads a trained model.

client.download_model(
    job_name="my-model",
    output_path="path/to/save/model.tar.gz"
)

Parameters:

  • job_name (str, required): The name of the job/model to download
  • output_path (str, required): The path where the model should be saved

Returns: None. Prints a success message when the download is complete.

list_deployments(job_name)

Lists all deployments for a specific job/model.

deployments = client.list_deployments("my-model")

Parameters:

  • job_name (str, required): The name of the job/model

Returns: A list of dictionaries, each containing information about a deployment.

deploy_model(job_name)

Deploys a trained model.

result = client.deploy_model("my-model")

Parameters:

  • job_name (str, required): The name of the job/model to deploy

Returns: A dictionary containing information about the deployment.

Metrics & Logs

get_stored_metrics(run_id)

Gets stored metrics for a specific run.

metrics = client.get_stored_metrics("run-123")

Parameters:

  • run_id (str, required): The ID of the run

Returns: A dictionary containing metrics for the run.

get_stored_logs(run_id, max_lines=2000)

Gets stored logs for a specific run.

logs = client.get_stored_logs(
    run_id="run-123",
    max_lines=2000  # Optional, defaults to 2000
)

Parameters:

  • run_id (str, required): The ID of the run
  • max_lines (int, optional): Maximum number of log lines to retrieve. Defaults to 2000

Returns: A dictionary containing logs for the run.

stream_logs(run_id, follow=True)

Streams logs for a specific run in real-time.

# This returns an async generator, so you need to use it in an async context
async for log_entry in client.stream_logs("run-123", follow=True):
    print(log_entry)

Parameters:

  • run_id (str, required): The ID of the run
  • follow (bool, optional): Whether to continue streaming new logs as they arrive. Defaults to True

Returns: An async generator that yields log entries as dictionaries.

GPU Prices

get_gpu_price(gpu_type)

Gets the price for a specific GPU type.

price = client.get_gpu_price("H100")

Parameters:

  • gpu_type (str, required): The type of GPU

Returns: A dictionary containing pricing information.

get_all_gpu_prices()

Gets prices for all available GPU types.

prices = client.get_all_gpu_prices()

Returns: A list of dictionaries, each containing pricing information for a GPU type.

Error Handling

The RunRL client defines several exception classes for handling different types of errors:

from runrl import (
    RunRLError,           # Base exception class
    AuthenticationError,  # Authentication failed
    PermissionError,      # Permission denied
    NotFoundError,        # Resource not found
    APIServerError,       # Server error
    RequestError          # Client request error
)

try:
    # RunRL API call
    client.get_run_details("non-existent-run")
except NotFoundError as e:
    print(f"Run not found: {e}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RunRLError as e:
    print(f"General error: {e}")

Authentication

How to authenticate with the RunRL API

File Formats

Detailed guide on how to format prompt files and reward functions for RunRL

On this page