Installation
Quick Start
Configuration
Retries and launches
Reads, updates and deletes are retried on 429, 5xx, timeouts and lost connections, honouringRetry-After up to 60 seconds. A request that creates or launches something is never sent twice by accident:
- Job submits and reruns send an
Idempotency-Key(a new one per call, reused on its retries), which the server honours, so they are retried like reads: a retry after a timeout answers the first job. - Instance, schedule and volume creates also send an
Idempotency-Key, but those routes do not deduplicate it yet;schedules.run_nowsends none. Once one of these, or a run-now, may have reached Runcrate (a timeout, a lost connection, a 500, 502 or 504), it is not sent again and the error is raised: checkclient.instances.list()before launching again. Only a 429 or 503, which say nothing was launched, and a connection that never opened are retried. - A launch waits at least 75 seconds for its answer (a job submit 135), whatever
timeoutis, so the client does not give up while the server is still launching. - A
502withcodelaunch_refusedis never retried: the same request is refused the same way.
Environments
API keys are workspace-scoped. By default, requests target the workspace’s default environment (usuallymain). To target a different environment, pass environment at client construction:
Async Support
Runcrate has an async equivalent on AsyncRuncrate.
Model Inference
All inference methods hitapi.runcrate.ai.
Chat Completions
Streaming
Image Generation
Model-Specific Parameters
All image methods accept extra keyword arguments that get passed through to the model. Different models support different parameters:Video Generation
seed, negative_prompt, image for image-to-video models) are passed through:
Text-to-Speech
speed or language are passed through:
Transcription
response_format you get the full object: text, duration, language and timed segments (the same as verbose_json). json gives text only.
Infrastructure Management
GPU Instances
max_runtime_minutes and idle_shutdown_minutes are optional and off when omitted. After an instance stops, instance.stop_reason says why: user, max_runtime, idle, budget, low_balance, failed or system. See Spend guardrails.
Environment Budgets
InsufficientCreditsError with e.code == "BUDGET_REACHED".
Schedules
A schedule starts an instance or a job later. Pass exactly one ofrun_at (once, a timezone-aware datetime or an ISO string with an offset) or cron (repeating, read in timezone). spec is the create body of the kind, and max_runtime_minutes is required in it.
Jobs
A job runs one command on its own fresh GPU machine, which stops (and stops billing) when the command ends. Files the command writes to$RUNCRATE_OUTPUT_DIR are kept 30 days.
upload = client.jobs.uploads.upload("./my-project"): it packs the directory as a tar.gz (without .git, __pycache__ and node_modules; a .tar.gz file or bytes work too, at most 1 GB) and sends it. Run with code={"upload_id": upload.upload_id} within 24 hours; the command runs in /workspace/code.
AsyncRuncrate has the same methods; follow_logs and list_all are async iterators. Pass your own idempotency_key to make a submit safe to repeat across processes: the same key with the same request answers the first job for 24 hours (see Idempotency). A low balance raises InsufficientCreditsError, a reached environment budget the same with code == "BUDGET_REACHED", and a bad field UnprocessableEntityError.
Secrets
The names of the secrets every machine in the client’s environment gets. Values are set in the dashboard and never returned. A value passed for one launch (env_vars) wins over a secret of the same name.
SSH Keys
Storage
Storage volumes are environment-scoped. Your workspace’s storage must be set up in the dashboard first; the SDK picks it up automatically.$0.03/GB/month, charged weekly in advance. Deletion refunds the unused portion of the current billing week.
Billing
idempotency_key, top_up makes a UUID and returns it on the answer. Every method has an async equivalent on AsyncRuncrate. See Top up by API for the permission, caps and statuses.
Templates
Error Handling
All API errors include the actual error message from the server, never a generic fallback.e.message: human-readable error description from the APIe.status_code: HTTP status codee.code: machine-readable error code (e.g.not_found,rate_limited)e.details: additional details (when available)