How to beginner · 3 min read

OpenAI run status types explained

Quick answer

OpenAI run status types indicate the state of an API request or job. Common statuses include succeeded (completed successfully), running (in progress), failed (error occurred), and canceled (stopped before completion). These help developers track and manage asynchronous or long-running tasks.

PREREQUISITES

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

Setup

Install the official openai Python SDK version 1 or higher and set your API key as an environment variable.

Install SDK: pip install openai>=1.0
Set environment variable in your shell: export OPENAI_API_KEY='your_api_key'

bash

pip install openai>=1.0

Step by step

This example demonstrates how to check the run status of an OpenAI job using the Python SDK. The status field in the response indicates the run status type.

python

import os
from openai import OpenAI

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

# Example: create a chat completion and check status
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello, what is the run status?"}]
)

# The response object may include a 'status' field for async jobs
# For synchronous calls, status is implicitly 'succeeded'

print("Run status:", getattr(response, 'status', 'succeeded'))
print("Response text:", response.choices[0].message.content)

output

Run status: succeeded
Response text: The run status indicates the current state of your API request or job.

Common variations

Run status types vary by API endpoint and usage:

succeeded: The job completed successfully.
running: The job is still processing (common in async endpoints).
failed: The job encountered an error.
canceled: The job was canceled before completion.

Use async calls or polling to check status for long-running jobs.

Run status type	Description
succeeded	Job completed successfully
running	Job is currently in progress
failed	Job encountered an error
canceled	Job was canceled before finishing

Troubleshooting

If you see a failed status, check the error message in the response for details. For running status, implement polling with delays to wait for completion. If jobs are unexpectedly canceled, verify your cancellation logic or API usage limits.

✅

Key Takeaways

Use the status field to track OpenAI job states programmatically.
Common run statuses are succeeded, running, failed, and canceled.
Polling is necessary for asynchronous jobs to detect when they finish or fail.

Verified 2026-04 · gpt-4o

Verify ↗