How to beginner · 3 min read

How to create a run in OpenAI Assistants API

Q: How to create a run in OpenAI Assistants API

Use the OpenAI Python SDK to create a run by calling client.assistants.runs.create() with the assistant ID and messages array. This sends a conversation turn to the assistant and returns the run details including the assistant's response.

Quick answer

Use the OpenAI Python SDK to create a run by calling client.assistants.runs.create() with the assistant ID and messages array. This sends a conversation turn to the assistant and returns the run details including the assistant's response.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official OpenAI Python SDK and set your API key as an environment variable.

Run pip install openai to install the SDK.
Set your API key in your shell: export OPENAI_API_KEY='your_api_key_here' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key_here" (Windows).

bash

pip install openai

Step by step

Use the OpenAI client to create a run by specifying the assistant ID and the conversation messages. The response contains the assistant's reply and run metadata.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.assistants.runs.create(
    assistant="your-assistant-id",
    messages=[{"role": "user", "content": "Hello, how can you assist me today?"}]
)

print("Run ID:", response.id)
print("Assistant reply:", response.choices[0].message.content)

output

Run ID: run-abc123xyz
Assistant reply: Hello! I can help you with a variety of tasks. What do you need assistance with today?

Common variations

You can customize the run by changing the messages array to include system or assistant roles, or use different assistants by changing the assistant ID. Async calls and streaming are not currently supported in the Assistants API.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Example with system message included
response = client.assistants.runs.create(
    assistant="your-assistant-id",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Tell me a joke."}
    ]
)

print(response.choices[0].message.content)

output

Why did the scarecrow win an award? Because he was outstanding in his field!

Troubleshooting

If you get an authentication error, verify your OPENAI_API_KEY environment variable is set correctly.
If the assistant ID is invalid, check that you have the correct assistant created in your OpenAI dashboard.
For unexpected errors, ensure you are using the latest openai SDK version and your network connection is stable.

✅

Key Takeaways

Use client.assistants.runs.create() with the assistant ID and messages to create a run.
Always set your API key in os.environ["OPENAI_API_KEY"] for authentication.
Include system messages in the messages array to guide assistant behavior.
Check your assistant ID and SDK version if you encounter errors.
The response contains the run ID and assistant's reply in response.choices[0].message.content.

Verified 2026-04 · gpt-4o, openai-assistants

Verify ↗