Python SDK Reference

The SDK exposes resource-oriented helpers that map directly to the REST API. All responses are Pydantic models, and long-running operations return futures.

Clients

`RunRLClient(**config)`

Parameter	Type	Description
`api_key`	str	Overrides `RUNRL_API_KEY` environment variable.
`base_url`	str	Defaults to `https://runrl.com/api/v1`.
`timeout`	float	HTTP timeout in seconds (default 30).
`poll_interval`	float	Seconds between polling future status (default 5).
`max_poll_timeout`	float	Maximum seconds futures will wait (default 3600).

Attributes:

files, runs, deployments, tools, shared_configurations, validation, search, api_keys
config – resolved ClientConfig
close() – close underlying httpx.Client

`AsyncRunRLClient(**config)`

Same configuration, but all methods are async. Use with async with ... or call await client.aclose().

Files

Namespace: client.files

Method	Description
`list(type=None, search=None, page=1, per_page=20, sort=None, direction=None)`	Returns `PagedResponse[File]`.
`retrieve(file_id)`	Fetch a single `File`.
`upload_path(path, file_type, name=None)`	Upload via multipart. `file_type` in `{prompt, reward_function, environment, sft}`.
`create_from_content(name, content, file_type, original_filename=None)`	Create from string content (reward/env).
`content(file_id)`	Return raw text content (raises if not text).
`preview(file_id, lines=20)`	Return preview payload for prompts or code.
`delete(file_id, force=False)`	Soft-delete by default; `force=True` purges permanently.

Async equivalents exist under client.files on AsyncRunRLClient.

Runs

Namespace: client.runs

Method	Description
`list(**filters)`	Paginated list of runs (`status`, `created_after`, `page`, etc.).
`get(run_id)`	Fetch latest run state.
`history(run_id)`	Status history records.
`logs(run_id, last_line=0, limit=100)`	Pull batched logs.
`stream_logs(run_id)`	Generator of SSE log lines.
`metrics(run_id)`	Weights & Biases metrics snapshot.
`completions(run_id)`	Stored completions payload.
`cancel(run_id)`	Request cancellation.
`create(**payload)`	Launch run and return `RunRLPollingFuture[Run]`.

RunRLPollingFuture exposes .initial, .status(), .result(timeout=None), .cancel(), and .add_done_callback(fn).

Async methods mirror the same signatures and return AsyncRunRLPollingFuture.

Payload fields for create:

model (str, required)
prompt_file_id (str, required)
reward_file_id (str, required)
type (reward_function or environment)
completion_length (int, optional, 128-8192, default 1024)
epochs (int, optional, 1-100, default 1)
learning_rate_multiplier (float, optional, default 1.0)
sft_file_id, tool_ids, package_requirements, hf_token

LoRA (Low-Rank Adaptation) Parameters:

use_lora (bool, optional, default False) – Enable parameter-efficient fine-tuning
lora_rank (int, optional, default 16) – LoRA rank, controls adaptation capacity (0 = disabled)
lora_alpha (int, optional, default 16) – Scaling factor, typically 2× rank
lora_dropout (float, optional, default 0) – Dropout rate for regularization

LoRA enables 2-3× faster training with significantly reduced memory usage, making it ideal for larger models on limited hardware.

Deployments

Namespace: client.deployments

Method	Description
`list(**filters)`	Returns `PagedResponse[Deployment]`.
`get(deployment_id)`	Fetch deployment details.
`check(run_id)`	Validate deploy-ability before creating.
`create(run_id, poll_interval=None, max_timeout=None)`	Returns `RunRLPollingFuture[Deployment]`.
`delete(deployment_id)`	Remove deployment (soft delete).

Tools

Namespace: client.tools

list(search=None, verified=None, owned_only=False, public_only=False, page=1, per_page=20, sort=None, direction=None) → PagedResponse[Tool]
create(name, mcp_url, description=None, is_public=False) → Tool
get(tool_id) → Tool
update(tool_id, **fields) → Tool
delete(tool_id)
test_connection(mcp_url) → Diagnostics payload

Shared Configurations

Namespace: client.shared_configurations

list() → Owned configurations
browse(**filters) → Paginated public/unlisted results
get(uuid) → SharedConfiguration
data(uuid) → Full payload including file previews
create(...) → SharedConfiguration
copy(uuid) → dict with new UUID + file IDs
like(uuid) → dict with liked flag
update(uuid, **fields) → SharedConfiguration
delete(uuid)

Validation

Namespace: client.validation

reward_function(code, mode="function", prompt_file_id=None) → ValidationResponse
prompt_file(prompt_file_id) → ValidationResponse
sft_file(sft_file_id) → ValidationResponse

Search

Namespace: client.search

query(q: str) → SearchResults containing runs, files, and tools lists.

API Keys

Namespace: client.api_keys

list() → [ApiKey]
create(name, scopes=None, requests_per_hour=None, expires_at=None) → ApiKeyToken
update(api_key_id, **fields) → ApiKey
usage(api_key_id) → usage stats dict
delete(api_key_id)

Models

All responses are defined in runrl.models:

File
Run
Deployment
Tool
SharedConfiguration
ValidationResponse
SearchResults
ApiKey
ApiKeyToken
PagedResponse

Use these models directly if you need typed validation or serialization within your application.

API Reference