Runback
Docs menuQuickstart: Python

    ↑↓ move ↵ open esc close

    Docs Start

    Quickstart: Python

    Record one OpenAI call from a Python script as a Runback run, then open it in the app. About five minutes.

    Before you begin

    • A Runback account. Create one free.
    • Python 3.9 or later. Check with python3 --version.
    • An OpenAI API key, set as OPENAI_API_KEY. No OpenAI key? Step 4 has a test command that needs none.

    Steps

    1. Get a Runback key

      A key tells Runback which workspace a run belongs to. Use a Send only key: it can send runs and nothing else.In the app, open Settings › Keys and access › API key, keep Send only selected, select Generate API key and copy it. It is shown once, and starts rb_cloud_. Creating keys needs a workspace admin; whoever created the workspace is one.

      Checking your session…

    2. Install the SDK

      Install Runback's Python SDK with the OpenAI extra, which also installs the OpenAI client. A virtual environment is recommended.

      terminalShell
      pip install "runback-sdk[openai]"
      Expected output

      pip ends with a Successfully installed line and no errors.

    3. Put your key in your shell

      Runback's SDKs and the test script read the key from the RUNBACK_API_KEY environment variable. Replace the placeholder with the key from step 1. If you signed in, step 1 has already filled it in.

      terminalShell
      export RUNBACK_API_KEY="<RUNBACK_API_KEY>"
      Expected output

      Nothing is printed. To check it is set, run echo $RUNBACK_API_KEY; it should print your key, starting rb_cloud_.

    4. Record a model call

      Save this as agent.py and run it with OPENAI_API_KEY set. It makes one OpenAI call through the wrapped client, so the call is recorded as a run named quickstart-agent.

      agent.pyPython
      # agent.py: run with OPENAI_API_KEY=sk-... python agent.py
import openai
from runback import Collector
from runback.openai import wrap_openai

task = "Say hello in three words."
run = Collector(run_name="quickstart-agent", input=task)
client = wrap_openai(openai.OpenAI(), run)

res = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": task}],
)
answer = res.choices[0].message.content

run.finish(output=answer)
print(answer)
      terminalShell
      OPENAI_API_KEY=sk-... python agent.py
      Expected output

      The model's short reply, for example Hello there, friend. and nothing else. A line starting [runback] means the run was not sent: see Troubleshooting below.

      No OpenAI key? Skip this step and send a test run instead. It uses the RUNBACK_API_KEY you exported and installs nothing.

      terminalShell
      curl -fsSL https://runback.dev/api/quickstart | bash

    5. Check the run arrived

      Open Runs in the app. Your run is at the top, named quickstart-agent. Open it to step through what the agent did.

    Troubleshooting

    You seeWhat it meansFix
    [runback] no RUNBACK_API_KEY set — dropped 3 eventsThe key is not set in the terminal you ran the agent from.Run step 3 again in the same terminal (a new terminal tab starts without it), then run the agent again.
    [runback] ingest failed 401 {"error":"Invalid API key"}Runback rejected the key: mistyped, revoked or expired.Copy the whole key again, or create a new one in Settings › Keys and access › API key.
    ModuleNotFoundError: No module named 'runback'The package went into a different Python environment.Activate the virtual environment you installed into, or run python -m pip install "runback-sdk[openai]" with the same python you run the agent with.
    openai.OpenAIError: Missing credentialsOPENAI_API_KEY is not set.Run the agent as OPENAI_API_KEY=sk-... python agent.py, or use the test-run command under step 4.
    The agent printed its reply but the run is not in RunsThe key belongs to a different workspace, or you are looking at the shared demo.Check the workspace name in the top right of the app is the one the key came from.

    Your agent never fails because of Runback: if recording fails, the model call still returns and Runback prints one [runback] line saying why.

    What the wrapper records

    wrap_openai records chat.completions and responses calls, sync or async, streamed or not. Tool results you send back in the next request become tool steps paired with the model's call. Your model call is unchanged: errors are recorded, then re-raised. Redaction runs inside your process before anything is sent.

    Next steps

    • Anthropic, LangGraph or the OpenAI Agents SDK? See Integrations.
    • See what the run you sent contains: Capture.
    • Stop a risky tool call before it runs: pass decide=True to Collector; see Control.
    Last updated 2 Nov 2026.