On this page · 12 sections
- What actually shuts down, and what does not
- The four object mappings
- Runs to responses: the polling loop disappears
- Threads to conversations, and the backfill nobody will do for you
- The part that is not feature parity
- What OpenAI's migration guide does not cover
- What this does to your token bill
- A 36-day plan
- India-specific considerations
- FAQ
- How eCorpIT can help
- References
Summary. OpenAI's Assistants API stops working on 26 August 2026, which is 36 days from 21 July 2026. OpenAI announced the deprecation on 26 August 2025 with a 12-month runway, and the shutdown date is now published on the official deprecations page. Four object types change: Assistants become Prompts, Threads become Conversations, Runs become Responses, and Run steps become Items. Three of those swaps are mechanical. One is not: prompts can only be created in the OpenAI dashboard, so any application that creates assistants programmatically has no like-for-like replacement. OpenAI has also confirmed in writing that it will not ship a tool to move your data: "We will not provide an automated tool for migrating Threads to Conversations." Budget for the token bill too. On GPT-5.5 the API costs $5.00 per 1M input tokens against $0.50 per 1M cached input tokens, and OpenAI states that chaining with previous_response_id still bills every prior input token in the chain. OpenAI claims a 40% to 80% improvement in cache utilisation on Responses versus Chat Completions in internal tests. This article covers the object mapping, working code for each swap, the four areas OpenAI's own migration guide does not document, and a 36-day plan.
What actually shuts down, and what does not
Two deprecations are running at once and they get confused constantly.
The Assistants API is being shut down. OpenAI's deprecations page records it plainly: "On August 26th, 2025, we notified developers using the Assistants API of its deprecation and removal from the API one year later, on August 26, 2026." The replacement listed against that shutdown date is the Responses API and the Conversations API.
Chat Completions is not being shut down. OpenAI's migrate-to-responses guide says the opposite twice: "While Chat Completions remains supported, Responses is recommended for all new projects" and "Chat Completions remains supported, so you can migrate one user flow at a time." If your team has been putting off a Chat Completions migration, that clock is not the one running out.
The announcement came from Edwin Arbus, posting OpenAI's official notice in the Announcements category of the OpenAI developer forum on 26 August 2025: "We're winding down the Assistants API beta. It will sunset one year from now, August 26, 2026." The same post explains the reasoning: "Based on your feedback, we've folded the best parts of Assistants into Responses, including code interpreter and persistent conversations." It also claims the Responses API "has already overtaken Chat Completions in token activity."
One more wrinkle sits in the migration guide and is easy to miss. The recommended replacement for assistant objects is itself already deprecated. OpenAI writes: "Reusable prompt objects are also being deprecated. If you use this migration path, review the prompts deprecation timeline before adopting prompt objects in a long-lived integration." No shutdown date for prompt objects is published. If you are choosing an architecture this month, that sentence should push you toward holding your configuration in your own source control rather than in OpenAI's prompt objects.
The four object mappings
This is the mapping table exactly as OpenAI publishes it in the Assistants migration guide, with the engineering consequence added.
| Assistants API object | Responses API replacement | What it means for your code |
|---|---|---|
Assistants |
Prompts |
Configuration moves to a dashboard-created, versioned object. There is no API to create one. |
Threads |
Conversations |
Server-side state survives, but stores items rather than only messages. No automated migration. |
Runs |
Responses |
The async run lifecycle disappears. You send input items and get output items back. |
Run steps |
Items |
Steps become a union type covering messages, tool calls, tool outputs and more. |
| Server-managed tool loop | Your orchestration code | OpenAI states tool call loops are "explicitly managed" by your application. |
The last row is the one that costs the most engineering time and it is the one teams underestimate. OpenAI's own framing is blunt: "Your application code now handles orchestration (history pruning, tool loop, retries) while your prompt focuses on high-level behavior and constraints."
Runs to responses: the polling loop disappears
Under the Assistants API you created a run against a thread and then polled it. OpenAI's guide shows this shape:
thread_id = "thread_CrXtCzcyEQbkAcXuNmVSKFs1"
assistant_id = "asst_8fVY45hU3IM6creFkVi5MBKB"
run = openai.beta.threads.runs.create(
thread_id=thread_id,
assistant_id=assistant_id,
)
while run.status in ("queued", "in_progress"):
time.sleep(1)
run = openai.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)
The Responses equivalent has no loop. One call returns output:
response = openai.responses.create(
model="gpt-5.5",
input=[{"role": "user", "content": "What are the 5 Ds of dodgeball?"}],
conversation="conv_689667905b048191b4740501625afd940c7533ace33a2dab",
)
print(response.output_text)
Worth knowing before you copy from the docs: the Responses block as published in OpenAI's migration guide omits the comma after the input=[...] line and writes conversation: with a colon where a Python keyword argument needs =. The example above is that code corrected. The Assistants block in the same guide defines assistant_id and then passes assistant.id, and leaves the while body unindented. Treat the published snippets as pseudocode.
The response object also renames fields you are probably logging. Diffing the run and response payloads in OpenAI's guide shows usage.prompt_tokens and usage.completion_tokens becoming usage.input_tokens and usage.output_tokens, max_completion_tokens and max_prompt_tokens collapsing into max_output_tokens, truncation_strategy becoming truncation, and object: "thread.run" becoming object: "response". Anything parsing those keys in your billing dashboards or alerting breaks silently rather than loudly.
Threads to conversations, and the backfill nobody will do for you
Creating state is close to identical. Threads:
thread = openai.beta.threads.create(
messages=[{"role": "user", "content": "what are the 5 Ds of dodgeball?"}],
metadata={"user_id": "peter_le_fleur"},
)
Conversations:
conversation = openai.conversations.create(
items=[{"role": "user", "content": "what are the 5 Ds of dodgeball?"}],
metadata={"user_id": "peter_le_fleur"},
)
The difference is what they hold. OpenAI: "Threads could only store messages. Conversations store items, which can include messages, tool calls, tool outputs, and other data."
Moving existing history is your job. OpenAI's guide states: "We will not provide an automated tool for migrating Threads to Conversations. Instead, we recommend migrating new user threads onto conversations and backfilling old ones as necessary." That is the correct strategy for most products. Point new sessions at conversations now, and backfill on demand when a user opens an old session, rather than attempting a big-bang export of every thread you have ever created.
OpenAI publishes a backfill sketch. As published it never initialises messages before using +=, and the image branch reads item_content + [...] with no assignment, so image content is silently dropped. Corrected:
thread_id = "thread_EIpHrTAVe0OzoLQg3TXfvrkG"
messages = []
pages = openai.beta.threads.messages.list(thread_id=thread_id, order="asc")
for page in pages.iter_pages():
messages += page.data
items = []
for m in messages:
item_content = []
for content in m.content:
if content.type == "text":
content_type = "input_text" if m.role == "user" else "output_text"
item_content.append({"type": content_type, "text": content.text.value})
elif content.type == "image_url":
item_content.append({
"type": "input_image",
"image_url": content.image_url.url,
"detail": content.image_url.detail,
})
items.append({"role": m.role, "content": item_content})
conversation = openai.conversations.create(items=items)
Note the asymmetry the text branch encodes: user text becomes input_text, assistant text becomes output_text. Get that backwards and the model reads its own prior answers as user instructions.
Retention differs between the two new objects, and the distinction matters for anyone with a data policy to satisfy. OpenAI's documentation, quoted in the developer forum thread on the deprecation, states that response objects are saved for 30 days by default and can be disabled with store: false, while "Conversation objects and items in them are not subject to the 30 day TTL." A forum participant pushed back on that phrasing directly, asking OpenAI to "say what exact TTL you apply rather than which one you don't." As of 21 July 2026 that clarification has not been published.
The part that is not feature parity
OpenAI's position is that Responses reached feature parity before the deprecation was announced. On one specific point, developers disputed that on OpenAI's own forum the same week, and the objection still stands.
Assistants were created through the API. Prompts are not. OpenAI's guide: "Their replacement, prompts, can only be created in the dashboard, where you can version them as you develop your product." The prescribed migration step is a manual click: "Find these in the dashboard and click Create prompt."
Peter Harrison, a developer posting in that announcement thread on 27 August 2025, put the problem in one line: "My application is dynamically creating Assistants. I'm not sure how this is 'feature parity'. Is there a API way to create Prompts?" Another forum member, posting as _j, listed the same gap plus a second one: "There is no API to create a 'prompt' equivalent to what you could do with Assistants" and Assistants "had a working 'truncation' method that at least worked for a number of turns to limit the length of a conversation."
If your product creates an assistant per customer, per workspace or per document set, plan for this now. The workable pattern is to stop treating OpenAI as the store of record for configuration: keep instructions, tool schemas and model choice in your own database or repository, and pass them on each Responses call rather than referencing a prompt ID. That also sidesteps the fact that prompt objects are themselves deprecated. The real cost here is usually the config migration, not the request rewrite.
What OpenAI's migration guide does not cover
The Assistants migration guide is short. Four things that a production Assistants integration almost certainly depends on are not in it at all.
| Area | Covered in the Assistants migration guide? | Where the answer actually is |
|---|---|---|
file_search and vector stores |
No mention anywhere in the guide | File search tool guide |
code_interpreter |
Not in the guide; confirmed folded into Responses in OpenAI's forum announcement | Code interpreter guide |
| Streaming events | Not in the guide | Streaming responses guide |
Function calling and submit_tool_outputs |
Not in the guide beyond "explicitly managed" | Function calling guide |
On streaming, the Chat Completions migration guide does give the shape, and it applies: "Chat Completions streaming returns incremental chunks with a delta field. Responses streaming uses typed server-sent events. Update stream consumers to branch on each event's type." It names response.created, response.output_text.delta, response.completed and error for text, plus response.function_call_arguments.delta and response.function_call_arguments.done for function calls. Any handler written against Assistants stream events needs rewriting, not adapting.
On function definitions, the same guide documents two changes that will bite immediately. Function definitions move from externally tagged to internally tagged, meaning the name, description and parameters keys move up out of a nested function object. And strictness flips: "In Chat Completions, functions are non-strict by default. In Responses, omitting strict attempts strict mode; if the schema cannot be made compatible, Responses falls back to non-strict, best-effort function calling and returns the resolved tool with strict: false."
Tool calls and their results are now correlated explicitly: "In Responses, tool calls and their outputs are two distinct types of Items that are correlated using a call_id." OpenAI lists "Sending a function result without the matching call_id" among the most common migration errors.
What this does to your token bill
Migration changes your cost profile, not just your code. These are OpenAI's published list prices as of 21 July 2026, taken from the API pricing page.
| Model | Input per 1M tokens | Cached input per 1M tokens | Output per 1M tokens |
|---|---|---|---|
| GPT-5.5 | $5.00 | $0.50 | $30.00 |
| GPT-5.4 | $2.50 | $0.25 | $15.00 |
| GPT-5.4 mini | $0.75 | $0.075 | $4.50 |
Cached input is a tenth of the price of uncached input across all three tiers. That is why OpenAI's claim about caching is a cost claim rather than a performance one: it reports "lower costs due to improved cache utilization (40% to 80% improvement when compared to Chat Completions in internal tests)." OpenAI also reports "a 3% improvement in SWE-bench with same prompt and setup" for reasoning models on Responses. Both figures are OpenAI's internal tests, not independent benchmarks, and should be treated that way in a business case.
The trap is state. OpenAI states it twice, including in its list of common migration errors: "Assuming previous_response_id removes billing for prior context. Previous input tokens in the response chain are still billed as input tokens." Server-side state saves you code, not money. Long-running conversations grow their own bill linearly, and the only lever that changes the slope is history pruning, which is now your code's responsibility rather than the run object's truncation_strategy. Teams that had been relying on that setting to cap conversation length have to rebuild it. If you are modelling this ahead of a migration, our breakdown of GPT-5.6 inference costs for enterprise AI covers how the per-turn arithmetic compounds.
Batch processing takes 50% off inputs and outputs for asynchronous jobs. The hosted web search tool is billed at $10.00 per 1,000 calls, with search content tokens free.
A 36-day plan
There are 36 days between 21 July 2026 and the shutdown. That is enough for a staged migration and not enough for a rewrite, so stage it.
Week 1. Inventory. Count your assistant objects, thread volume, and which tools each assistant declares. Separate assistants created by hand from assistants created programmatically, because only the second group has a design problem. Move your instructions and tool schemas into source control.
Week 2. Rewrite the request path for one low-risk flow. Change the endpoint, replace the polling loop with a single Responses call, and read response.output_text instead of walking messages. Decide per flow whether state comes from a conversation object, from previous_response_id, or from replaying items yourself.
Week 3. Rebuild the tool loop and the streaming consumer. This is the largest block of work in most codebases. Verify every function result carries the matching call_id, and branch stream handling on event type. Do not port your Assistants stream handler.
Week 4. Backfill and cut over. Point new sessions at conversations, backfill old threads lazily when a user reopens one, and keep the Assistants path behind a flag until the traffic has moved. OpenAI's own rollout checklist ends with a sensible instruction: "Compare behavior, latency, token usage, and errors before routing more traffic to Responses." Instrument that comparison before you need it, not after; the same discipline applies to any model change, which is why evaluation and observability belongs in the migration rather than after it.
Days 29 to 36. Buffer. Something in the tool loop will surprise you.
India-specific considerations
For teams in India building on the Assistants API, two points deserve attention beyond the code.
The first is data retention under the Digital Personal Data Protection Act 2023. Responses are stored by default, and conversation items sit outside the documented 30-day TTL with no published retention period in its place. If your processing record says conversation content is retained for a defined period, a migration to conversation objects changes the factual basis of that statement. Setting store: false and replaying items yourself keeps retention under your control. Teams working through this in detail will find the ground rules in our DPDP engineering playbook for Indian startups.
The second is Zero Data Retention. OpenAI documents a specific path: "For ZDR organizations, OpenAI enforces store: false automatically," with encrypted reasoning items passed back on each request so that reasoning context survives without server-side storage. That path forecloses conversation objects entirely, so ZDR teams should plan on manual item replay from day one rather than migrating twice.
Both routes push you toward holding conversation state in your own infrastructure. That is more code, and it is the version of the architecture that survives the next deprecation, including the one already announced for prompt objects. The same reasoning applies to protocol churn elsewhere in the agent stack, as with the stateless MCP specification migration.
FAQ
How eCorpIT can help
eCorpIT builds and migrates production LLM integrations for teams in India and abroad, and an Assistants API cutover is a well-defined piece of work with a fixed deadline. Our senior engineering teams handle the parts that consume the schedule: rebuilding server-managed tool loops in application code, rewriting streaming consumers against typed events, and designing conversation state that satisfies DPDP and Zero Data Retention constraints. If you are running the Assistants API in production with 36 days left, talk to us about scoping the migration.
References
Last updated: 21 July 2026.
