How to beginner · 3 min read

How to poll run status in OpenAI Assistants API

Q: How to poll run status in OpenAI Assistants API

Use the client.assistants.runs.get() method with the run ID to poll the status of a run in the OpenAI Assistants API. Repeatedly call this endpoint until the status field indicates completion or failure.

Quick answer

Use the client.assistants.runs.get() method with the run ID to poll the status of a run in the OpenAI Assistants API. Repeatedly call this endpoint until the status field indicates completion or failure.

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

This example demonstrates how to start a run and poll its status until it completes or fails using the OpenAI SDK v1.

python

import os
import time
from openai import OpenAI

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

# Replace with your assistant ID and input
assistant_id = "your-assistant-id"
input_data = {"input": {"text": "Hello, run status!"}}

# Start a run
run_response = client.assistants.runs.create(
    assistant=assistant_id,
    input=input_data
)
run_id = run_response["id"]
print(f"Started run with ID: {run_id}")

# Poll run status until done
while True:
    run_status = client.assistants.runs.get(
        assistant=assistant_id,
        run=run_id
    )
    status = run_status.get("status")
    print(f"Run status: {status}")
    if status in ["succeeded", "failed", "cancelled"]:
        break
    time.sleep(2)  # wait before polling again

print("Final run response:")
print(run_status)

output

Started run with ID: run-abc123xyz
Run status: running
Run status: running
Run status: succeeded
Final run response:
{... full run response JSON ...}

Common variations

You can adapt polling for asynchronous or streaming use cases, or use different models and assistants. For example:

Use asyncio with await and async functions to poll asynchronously.
Adjust time.sleep() interval for faster or slower polling.
Use different assistant IDs or input payloads depending on your use case.

python

import asyncio
import os
from openai import OpenAI

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

async def poll_run_status(assistant_id, run_id):
    while True:
        run_status = client.assistants.runs.get(
            assistant=assistant_id,
            run=run_id
        )
        status = run_status.get("status")
        print(f"Run status: {status}")
        if status in ["succeeded", "failed", "cancelled"]:
            return run_status
        await asyncio.sleep(2)

# Usage example (requires an async context):
# asyncio.run(poll_run_status("your-assistant-id", "your-run-id"))

Troubleshooting

If you receive a 401 Unauthorized error, verify your OPENAI_API_KEY environment variable is set correctly.
If polling never completes, check the status field for error states like failed or cancelled.
For network errors, ensure your internet connection is stable and retry.

✅

Key Takeaways

Use client.assistants.runs.get() with the run ID to poll run status.
Poll repeatedly until the status is succeeded, failed, or cancelled.
Use time.sleep() or asyncio.sleep() to space out polling requests.
Ensure your OPENAI_API_KEY is set in the environment to avoid authentication errors.

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

Verify ↗