openai / openai/openai-python

responses.parse() with background=True returns unparseable Response from retrieve() - missing ParsedResponse support for background mode

Open
#2,830 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Python
Stars
31.6k
Forks
5.7k
Avg merge
1d 6h
Merged PRs (30d)
96

Description

Confirm this is an issue with the Python library and not an underlying OpenAI API
  • This is an issue with the Python library
Describe the bug

When using responses.parse() with background=True and a text_format (structured output), the initial call returns a ParsedResponse wrapper. However, when polling for completion using responses.retrieve(), a plain Response object is returned instead of ParsedResponse.

This means output_parsed is not available on the retrieved response, and users must manually parse output_text using their schema's model_validate_json().

The SDK accepts background=True in parse() without warning, but doesn't provide a way to complete the workflow with proper parsing.

Expected behavior:
Either:

  • retrieve() should accept a text_format parameter to return ParsedResponse
    A new retrieve_parsed() method should exist
  • Or parse() should raise an error/warning when background=True is used
To Reproduce

from openai import AsyncOpenAI
from pydantic import BaseModel

class MySchema(BaseModel):
name: str
value: int

client = AsyncOpenAI()

Start background request with structured output

response = await client.responses.parse(
model="gpt-4.1",
input="Generate a name and value",
text_format=MySchema,
background=True
)

Poll for completion

while response.status in ("in_progress", "queued"):
await asyncio.sleep(0.5)
response = await client.responses.retrieve(response.id)

This fails - Response has no output_parsed attribute

print(response.output_parsed) # AttributeError: 'Response' object has no attribute 'output_parsed'

Workaround required:

result = MySchema.model_validate_json(response.output_text)

Code snippets

OS

macOS

Python version

Python v3.12

Library version

openai v2.15.0

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the responses.parse() and responses.retrieve() entry points and run the provided AsyncOpenAI reproduction using background=True and MySchema. Trace how each call constructs its response, then define completion as either preserving parsed output through retrieval or clearly rejecting the unsupported workflow, with coverage for the chosen behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.