Documentation 2026-08-26 22:57 UTC to 2026-08-27 22:01 UTC

1# Assistants API deep dive

2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 

5After achieving feature parity in the Responses API, we've deprecated the Assistants API. It will shut down on August 26, 2026. Follow the [migration guide](https://developers.openai.com/platform/assistants/migration) to update your integration. [Learn more](https://platform.openai.com/docs/guides/migrate-to-responses).

6 

7## Overview

8 

9Don't start a new integration on the Assistants API. We've announced plans to deprecate it soon, as the Responses API now provides the same features and a more elegant integration.

10 

11There are several concepts involved in building an app with the Assistants API, covered below in case it helps with your [migration to Responses](https://developers.openai.com/api/docs/assistants/migration).

12 

13## Creating assistants

14 

15We recommend using OpenAI's [latest models](https://developers.openai.com/api/docs/models) with

16 the Assistants API for best results and maximum compatibility with tools.

17 

18To get started, creating an Assistant only requires specifying the `model` to use. But you can further customize the behavior of the Assistant:

19 

201. Use the `instructions` parameter to guide the personality of the Assistant and define its goals. Instructions are similar to system messages in the Chat Completions API.

212. Use the `tools` parameter to give the Assistant access to up to 128 tools. You can give it access to OpenAI built-in tools like `code_interpreter` and `file_search`, or call a third-party tools via a `function` calling.

223. Use the `tool_resources` parameter to give the tools like `code_interpreter` and `file_search` access to files. Files are uploaded using the `File` [upload endpoint](https://developers.openai.com/api/reference/resources/files/methods/create) and must have the `purpose` set to `assistants` to be used with this API.

23 

24For example, to create an Assistant that can create data visualization based on a `.csv` file, first upload a file.

25 

26```javascript

27const file = await openai.files.create({

28 file: fs.createReadStream("revenue-forecast.csv"),

29 purpose: "assistants",

30});

31```

32 

33```python

34file = client.files.create(

35 file=open("revenue-forecast.csv", "rb"), purpose="assistants"

36)

37```

38 

39```go

40input, err := os.Open("revenue-forecast.csv")

41if err != nil {

42 panic(err)

43}

44defer input.Close()

45file, err := client.Files.New(context.Background(), openai.FileNewParams{

46 File: input,

47 Purpose: openai.FilePurposeAssistants,

48})

49if err != nil {

50 panic(err)

51}

52```

53 

54```java

55import com.openai.client.OpenAIClient;

56import com.openai.client.okhttp.OpenAIOkHttpClient;

57import com.openai.models.files.FileCreateParams;

58import com.openai.models.files.FilePurpose;

59import java.nio.file.Path;

60 

61var file =

62 client

63 .files()

64 .create(

65 FileCreateParams.builder()

66 .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))

67 .purpose(FilePurpose.ASSISTANTS)

68 .build());

69 

70System.out.println(file.id());

71```

72 

73```ruby

74require "openai"

75require "pathname"

76 

77client = OpenAI::Client.new

78file = Pathname("revenue-forecast.csv")

79uploaded = client.files.create(file: file, purpose: :assistants)

80puts(uploaded.id)

81```

82 

83```bash

84curl https://api.openai.com/v1/files \

85 -H "Authorization: Bearer $OPENAI_API_KEY" \

86 -F purpose="assistants" \

87 -F file="@revenue-forecast.csv"

88```

89 

90 

91Then, create the Assistant with the `code_interpreter` tool enabled and provide the file as a resource to the tool.

92 

93```javascript

94const assistant = await openai.beta.assistants.create({

95 name: "Data visualizer",

96 description:

97 "You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",

98 model: "gpt-4o",

99 tools: [{ type: "code_interpreter" }],

100 tool_resources: {

101 code_interpreter: {

102 file_ids: [file.id],

103 },

104 },

105});

106```

107 

108```python

109assistant = client.beta.assistants.create(

110 name="Data visualizer",

111 description="You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",

112 model="gpt-4o",

113 tools=[{"type": "code_interpreter"}],

114 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

115)

116```

117 

118```go

119assistant, err := client.Beta.Assistants.New(context.Background(), openai.BetaAssistantNewParams{

120 Name: openai.String("Data visualizer"),

121 Description: openai.String("You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed."),

122 Model: shared.ChatModelGPT4o,

123 Tools: []openai.AssistantToolUnionParam{{OfCodeInterpreter: &openai.CodeInterpreterToolParam{}}},

124 ToolResources: openai.BetaAssistantNewParamsToolResources{

125 CodeInterpreter: openai.BetaAssistantNewParamsToolResourcesCodeInterpreter{FileIDs: []string{"file-BK7bzQj3FfZFXr7DbL6xJwfo"}},

126 },

127})

128if err != nil {

129 panic(err)

130}

131```

132 

133```java

134import com.openai.client.OpenAIClient;

135import com.openai.client.okhttp.OpenAIOkHttpClient;

136import com.openai.models.beta.assistants.AssistantCreateParams;

137import com.openai.models.beta.assistants.CodeInterpreterTool;

138 

139String fileId = "file-BK7bzQj3FfZFXr7DbL6xJwfo";

140 

141var assistant =

142 client

143 .beta()

144 .assistants()

145 .create(

146 AssistantCreateParams.builder()

147 .name("Data visualizer")

148 .model("gpt-4o")

149 .description(

150 "You are great at creating beautiful data visualizations. You analyze data"

151 + " present in .csv files, understand trends, and come up with data"

152 + " visualizations relevant to those trends. You also share a brief text"

153 + " summary of the trends observed.")

154 .addTool(CodeInterpreterTool.builder().build())

155 .toolResources(

156 AssistantCreateParams.ToolResources.builder()

157 .codeInterpreter(

158 AssistantCreateParams.ToolResources.CodeInterpreter.builder()

159 .addFileId(fileId)

160 .build())

161 .build())

162 .build());

163 

164System.out.println(assistant.id());

165```

166 

167```ruby

168require "openai"

169 

170client = OpenAI::Client.new

171assistant = client.beta.assistants.create(

172 name: "Data visualizer",

173 model: "gpt-4o",

174 instructions: "Analyze CSV data, create relevant visualizations, and summarize the trends.",

175 tools: [{type: :code_interpreter}],

176 tool_resources: {

177 code_interpreter: {file_ids: ["file-BK7bzQj3FfZFXr7DbL6xJwfo"]}

178 }

179)

180puts(assistant.id)

181```

182 

183```bash

184curl https://api.openai.com/v1/assistants \

185 -H "Authorization: Bearer $OPENAI_API_KEY" \

186 -H "Content-Type: application/json" \

187 -H "OpenAI-Beta: assistants=v2" \

188 -d '{

189 "name": "Data visualizer",

190 "description": "You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",

191 "model": "gpt-4o",

192 "tools": [{"type": "code_interpreter"}],

193 "tool_resources": {

194 "code_interpreter": {

195 "file_ids": ["file-BK7bzQj3FfZFXr7DbL6xJwfo"]

196 }

197 }

198 }'

199```

200 

201 

202You can attach a maximum of 20 files to `code_interpreter` and 10,000 files to `file_search` (using `vector_store` [objects](https://developers.openai.com/api/reference/resources/vector_stores)). For vector stores created starting in November 2025, the `file_search` limit is 100,000,000 files.

203 

204Each file can be at most 512 MB in size and have a maximum of 5,000,000 tokens. By default, each project can store up to 2.5 TB of files total. There is no organization-wide storage limit. You can reach out to our support team to increase this limit.

205 

206## Managing Threads and Messages

207 

208Threads and Messages represent a conversation session between an Assistant and a user. There is a limit of 100,000 Messages per Thread. Once the size of the Messages exceeds the context window of the model, the Thread will attempt to smartly truncate messages, before fully dropping the ones it considers the least important.

209 

210You can create a Thread with an initial list of Messages like this:

211 

212```javascript

213const thread = await openai.beta.threads.create({

214 messages: [

215 {

216 role: "user",

217 content: "Create 3 data visualizations based on the trends in this file.",

218 attachments: [

219 {

220 file_id: file.id,

221 tools: [{ type: "code_interpreter" }],

222 },

223 ],

224 },

225 ],

226});

227```

228 

229```python

230thread = client.beta.threads.create(

231 messages=[

232 {

233 "role": "user",

234 "content": "Create 3 data visualizations based on the trends in this file.",

235 "attachments": [

236 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

237 ],

238 }

239 ]

240)

241```

242 

243```go

244thread, err := client.Beta.Threads.New(context.Background(), openai.BetaThreadNewParams{

245 Messages: []openai.BetaThreadNewParamsMessage{{

246 Role: "user",

247 Content: openai.BetaThreadNewParamsMessageContentUnion{

248 OfString: openai.String("Create 3 data visualizations based on the trends in this file."),

249 },

250 Attachments: []openai.BetaThreadNewParamsMessageAttachment{{

251 FileID: openai.String("file-ACq8OjcLQm2eIG0BvRM4z5qX"),

252 Tools: []openai.BetaThreadNewParamsMessageAttachmentToolUnion{{OfCodeInterpreter: &openai.CodeInterpreterToolParam{}}},

253 }},

254 }},

255})

256if err != nil {

257 panic(err)

258}

259```

260 

261```java

262import com.openai.client.OpenAIClient;

263import com.openai.client.okhttp.OpenAIOkHttpClient;

264import com.openai.models.beta.assistants.CodeInterpreterTool;

265import com.openai.models.beta.threads.ThreadCreateParams;

266 

267String fileId = "file-ACq8OjcLQm2eIG0BvRM4z5qX";

268 

269var thread =

270 client

271 .beta()

272 .threads()

273 .create(

274 ThreadCreateParams.builder()

275 .addMessage(

276 ThreadCreateParams.Message.builder()

277 .role(ThreadCreateParams.Message.Role.USER)

278 .content(

279 "Create 3 data visualizations based on the trends in this file.")

280 .addAttachment(

281 ThreadCreateParams.Message.Attachment.builder()

282 .fileId(fileId)

283 .addTool(CodeInterpreterTool.builder().build())

284 .build())

285 .build())

286 .build());

287 

288System.out.println(thread.id());

289```

290 

291```ruby

292require "openai"

293 

294client = OpenAI::Client.new

295thread = client.beta.threads.create(

296 messages: [{

297 role: :user,

298 content: "Create 3 data visualizations based on the trends in this file.",

299 attachments: [{

300 file_id: "file-ACq8OjcLQm2eIG0BvRM4z5qX",

301 tools: [{type: :code_interpreter}]

302 }]

303 }]

304)

305puts(thread.id)

306```

307 

308```bash

309curl https://api.openai.com/v1/threads \

310 -H "Authorization: Bearer $OPENAI_API_KEY" \

311 -H "Content-Type: application/json" \

312 -H "OpenAI-Beta: assistants=v2" \

313 -d '{

314 "messages": [

315 {

316 "role": "user",

317 "content": "Create 3 data visualizations based on the trends in this file.",

318 "attachments": [

319 {

320 "file_id": "file-ACq8OjcLQm2eIG0BvRM4z5qX",

321 "tools": [{"type": "code_interpreter"}]

322 }

323 ]

324 }

325 ]

326 }'

327```

328 

329 

330Messages can contain text, images, or file attachment. Message `attachments` are helper methods that add files to a thread's `tool_resources`. You can also choose to add files to the `thread.tool_resources` directly.

331 

332### Creating image input content

333 

334Message content can contain either external image URLs or File IDs uploaded via the [File API](https://developers.openai.com/api/reference/resources/files/methods/create). Only [models](https://developers.openai.com/api/docs/models) with Vision support can accept image input. Supported image content types include png, jpg, gif, and webp. When creating image files, pass `purpose="vision"` to allow you to later download and display the input content. Projects are limited to 2.5 TB total file storage, and there is no organization-wide storage limit. Please contact us to request a limit increase.

335 

336Tools cannot access image content unless specified. To pass image files to Code Interpreter, add the file ID in the message `attachments` list to allow the tool to read and analyze the input. Image URLs cannot be downloaded in Code Interpreter today.

337 

338```javascript

339import fs from "fs";

340 

341const file = await openai.files.create({

342 file: fs.createReadStream("myimage.png"),

343 purpose: "vision",

344});

345const thread = await openai.beta.threads.create({

346 messages: [

347 {

348 role: "user",

349 content: [

350 {

351 type: "text",

352 text: "What is the difference between these images?",

353 },

354 {

355 type: "image_url",

356 image_url: {

357 url: "https://openai-documentation.vercel.app/images/cat_and_otter.png",

358 },

359 },

360 {

361 type: "image_file",

362 image_file: { file_id: file.id },

363 },

364 ],

365 },

366 ],

367});

368```

369 

370```python

371file = client.files.create(file=open("myimage.png", "rb"), purpose="vision")

372thread = client.beta.threads.create(

373 messages=[

374 {

375 "role": "user",

376 "content": [

377 {

378 "type": "text",

379 "text": "What is the difference between these images?",

380 },

381 {

382 "type": "image_url",

383 "image_url": {

384 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"

385 },

386 },

387 {"type": "image_file", "image_file": {"file_id": file.id}},

388 ],

389 }

390 ]

391)

392```

393 

394```go

395image, err := os.Open("myimage.png")

396if err != nil {

397 panic(err)

398}

399defer image.Close()

400file, err := client.Files.New(context.Background(), openai.FileNewParams{

401 File: image,

402 Purpose: openai.FilePurposeVision,

403})

404if err != nil {

405 panic(err)

406}

407thread, err := client.Beta.Threads.New(context.Background(), openai.BetaThreadNewParams{

408 Messages: []openai.BetaThreadNewParamsMessage{{

409 Role: "user",

410 Content: openai.BetaThreadNewParamsMessageContentUnion{OfArrayOfContentParts: []openai.MessageContentPartParamUnion{

411 openai.MessageContentPartParamOfText("What is the difference between these images?"),

412 openai.MessageContentPartParamOfImageURL(openai.ImageURLParam{URL: "https://openai-documentation.vercel.app/images/cat_and_otter.png"}),

413 openai.MessageContentPartParamOfImageFile(openai.ImageFileParam{FileID: file.ID}),

414 }},

415 }},

416})

417if err != nil {

418 panic(err)

419}

420```

421 

422```java

423import com.openai.client.OpenAIClient;

424import com.openai.client.okhttp.OpenAIOkHttpClient;

425import com.openai.models.beta.threads.ThreadCreateParams;

426import com.openai.models.beta.threads.messages.ImageFile;

427import com.openai.models.beta.threads.messages.ImageFileContentBlock;

428import com.openai.models.beta.threads.messages.ImageUrl;

429import com.openai.models.beta.threads.messages.ImageUrlContentBlock;

430import com.openai.models.beta.threads.messages.MessageContentPartParam;

431import com.openai.models.beta.threads.messages.TextContentBlockParam;

432import com.openai.models.files.FileCreateParams;

433import com.openai.models.files.FilePurpose;

434import java.nio.file.Path;

435import java.util.List;

436 

437var file =

438 client

439 .files()

440 .create(

441 FileCreateParams.builder()

442 .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))

443 .purpose(FilePurpose.VISION)

444 .build());

445 

446var imageUrl =

447 ImageUrl.builder()

448 .url("https://openai-documentation.vercel.app/images/cat_and_otter.png")

449 .build();

450var thread =

451 client

452 .beta()

453 .threads()

454 .create(

455 ThreadCreateParams.builder()

456 .addMessage(

457 ThreadCreateParams.Message.builder()

458 .role(ThreadCreateParams.Message.Role.USER)

459 .content(

460 ThreadCreateParams.Message.Content.ofArrayOfContentParts(

461 List.of(

462 MessageContentPartParam.ofText(

463 TextContentBlockParam.builder()

464 .text(

465 "What is the difference between these images?")

466 .build()),

467 MessageContentPartParam.ofImageUrl(

468 ImageUrlContentBlock.builder()

469 .imageUrl(imageUrl)

470 .build()),

471 MessageContentPartParam.ofImageFile(

472 ImageFileContentBlock.builder()

473 .imageFile(

474 ImageFile.builder().fileId(file.id()).build())

475 .build()))))

476 .build())

477 .build());

478 

479System.out.println(thread.id());

480```

481 

482```ruby

483require "openai"

484require "pathname"

485 

486client = OpenAI::Client.new

487file = client.files.create(

488 file: Pathname("myimage.png"),

489 purpose: :vision

490)

491thread = client.beta.threads.create(

492 messages: [{

493 role: :user,

494 content: [

495 {type: :text, text: "What is the difference between these images?"},

496 {

497 type: :image_url,

498 image_url: {url: "https://openai-documentation.vercel.app/images/cat_and_otter.png"}

499 },

500 {type: :image_file, image_file: {file_id: file.id}}

501 ]

502 }]

503)

504puts(thread.id)

505```

506 

507```bash

508# Upload a file with an "vision" purpose

509curl https://api.openai.com/v1/files \

510 -H "Authorization: Bearer $OPENAI_API_KEY" \

511 -F purpose="vision" \

512 -F file="@/path/to/myimage.png"

513 

514## Pass the file ID in the content

515 

516curl https://api.openai.com/v1/threads \

517-H "Authorization: Bearer $OPENAI_API_KEY" \

518-H "Content-Type: application/json" \

519-H "OpenAI-Beta: assistants=v2" \

520-d '{

521"messages": [

522{

523"role": "user",

524"content": [

525{

526"type": "text",

527"text": "What is the difference between these images?"

528},

529{

530"type": "image_url",

531"image_url": {"url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"}

532},

533{

534"type": "image_file",

535"image_file": {"file_id": file.id}

536}

537]

538}

539]

540}'

541```

542 

543 

544#### Low or high fidelity image understanding

545 

546By controlling the `detail` parameter, which has three options, `low`, `high`, or `auto`, you have control over how the model processes the image and generates its textual understanding.

547 

548- `low` will enable the "low res" mode. The model will receive a low-res 512px x 512px version of the image, and represent the image with a budget of 85 tokens. This allows the API to return faster responses and consume fewer input tokens for use cases that do not require high detail.

549- `high` will enable "high res" mode, which first allows the model to see the low res image and then creates detailed crops of input images based on the input image size. Use the [pricing calculator](https://openai.com/api/pricing/) to see token counts for various image sizes.

550 

551```javascript

552const thread = await openai.beta.threads.create({

553 messages: [

554 {

555 role: "user",

556 content: [

557 {

558 type: "text",

559 text: "What is this an image of?",

560 },

561 {

562 type: "image_url",

563 image_url: {

564 url: "https://openai-documentation.vercel.app/images/cat_and_otter.png",

565 detail: "high",

566 },

567 },

568 ],

569 },

570 ],

571});

572```

573 

574```python

575thread = client.beta.threads.create(

576 messages=[

577 {

578 "role": "user",

579 "content": [

580 {"type": "text", "text": "What is this an image of?"},

581 {

582 "type": "image_url",

583 "image_url": {

584 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",

585 "detail": "high",

586 },

587 },

588 ],

589 }

590 ]

591)

592```

593 

594```go

595thread, err := client.Beta.Threads.New(context.Background(), openai.BetaThreadNewParams{

596 Messages: []openai.BetaThreadNewParamsMessage{{

597 Role: "user",

598 Content: openai.BetaThreadNewParamsMessageContentUnion{OfArrayOfContentParts: []openai.MessageContentPartParamUnion{

599 openai.MessageContentPartParamOfText("What is this an image of?"),

600 openai.MessageContentPartParamOfImageURL(openai.ImageURLParam{

601 URL: "https://openai-documentation.vercel.app/images/cat_and_otter.png",

602 Detail: openai.ImageURLDetailHigh,

603 }),

604 }},

605 }},

606})

607if err != nil {

608 panic(err)

609}

610```

611 

612```java

613import com.openai.client.OpenAIClient;

614import com.openai.client.okhttp.OpenAIOkHttpClient;

615import com.openai.models.beta.threads.ThreadCreateParams;

616import com.openai.models.beta.threads.messages.ImageUrl;

617import com.openai.models.beta.threads.messages.ImageUrlContentBlock;

618import com.openai.models.beta.threads.messages.MessageContentPartParam;

619import com.openai.models.beta.threads.messages.TextContentBlockParam;

620import java.util.List;

621 

622var thread =

623 client

624 .beta()

625 .threads()

626 .create(

627 ThreadCreateParams.builder()

628 .addMessage(

629 ThreadCreateParams.Message.builder()

630 .role(ThreadCreateParams.Message.Role.USER)

631 .content(

632 ThreadCreateParams.Message.Content.ofArrayOfContentParts(

633 List.of(

634 MessageContentPartParam.ofText(

635 TextContentBlockParam.builder()

636 .text("What is this an image of?")

637 .build()),

638 MessageContentPartParam.ofImageUrl(

639 ImageUrlContentBlock.builder()

640 .imageUrl(

641 ImageUrl.builder()

642 .url(

643 "https://openai-documentation.vercel.app/images/cat_and_otter.png")

644 .detail(ImageUrl.Detail.HIGH)

645 .build())

646 .build()))))

647 .build())

648 .build());

649 

650System.out.println(thread.id());

651```

652 

653```ruby

654require "openai"

655 

656client = OpenAI::Client.new

657thread = client.beta.threads.create(

658 messages: [{

659 role: :user,

660 content: [

661 {type: :text, text: "What is this an image of?"},

662 {

663 type: :image_url,

664 image_url: {

665 url: "https://openai-documentation.vercel.app/images/cat_and_otter.png",

666 detail: :high

667 }

668 }

669 ]

670 }]

671)

672puts(thread.id)

673```

674 

675```bash

676curl https://api.openai.com/v1/threads \

677 -H "Authorization: Bearer $OPENAI_API_KEY" \

678 -H "Content-Type: application/json" \

679 -H "OpenAI-Beta: assistants=v2" \

680 -d '{

681 "messages": [

682 {

683 "role": "user",

684 "content": [

685 {

686 "type": "text",

687 "text": "What is this an image of?"

688 },

689 {

690 "type": "image_url",

691 "image_url": {

692 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",

693 "detail": "high"

694 }

695 },

696 ]

697 }

698 ]

699 }'

700```

701 

702 

703### Context window management

704 

705The Assistants API automatically manages the truncation to ensure it stays within the model's maximum context length. You can customize this behavior by specifying the maximum tokens you'd like a run to utilize and/or the maximum number of recent messages you'd like to include in a run.

706 

707#### Max Completion and Max Prompt Tokens

708 

709To control the token usage in a single Run, set `max_prompt_tokens` and `max_completion_tokens` when creating the Run. These limits apply to the total number of tokens used in all completions throughout the Run's lifecycle.

710 

711For example, initiating a Run with `max_prompt_tokens` set to 500 and `max_completion_tokens` set to 1000 means the first completion will truncate the thread to 500 tokens and cap the output at 1000 tokens. If only 200 prompt tokens and 300 completion tokens are used in the first completion, the second completion will have available limits of 300 prompt tokens and 700 completion tokens.

712 

713If a completion reaches the `max_completion_tokens` limit, the Run will terminate with a status of `incomplete`, and details will be provided in the `incomplete_details` field of the Run object.

714 

715When using the File Search tool, we recommend setting the max_prompt_tokens to

716 no less than 20,000. For longer conversations or multiple interactions with

717 File Search, consider increasing this limit to 50,000, or ideally, removing

718 the max_prompt_tokens limits altogether to get the highest quality results.

719 

720#### Truncation Strategy

721 

722You may also specify a truncation strategy to control how your thread should be rendered into the model's context window.

723Using a truncation strategy of type `auto` will use OpenAI's default truncation strategy. Using a truncation strategy of type `last_messages` will allow you to specify the number of the most recent messages to include in the context window.

724 

725### Message annotations

726 

727Messages created by Assistants may contain [`annotations`](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/messages#messages/object-content) within the `content` array of the object. Annotations provide information around how you should annotate the text in the Message.

728 

729There are two types of Annotations:

730 

7311. `file_citation`: File citations are created by the [`file_search`](https://developers.openai.com/api/docs/assistants/tools/file-search) tool and define references to a specific file that was uploaded and used by the Assistant to generate the response.

7322. `file_path`: File path annotations are created by the [`code_interpreter`](https://developers.openai.com/api/docs/assistants/tools/code-interpreter) tool and contain references to the files generated by the tool.

733 

734When annotations are present in the Message object, you'll see illegible model-generated substrings in the text that you should replace with the annotations. These strings may look something like `【13†source】` or `sandbox:/mnt/data/file.csv`. Here’s an example python code snippet that replaces these strings with the annotations.

735 

736```python

737import os

738from pathlib import Path

739 

740thread_id = os.environ["OPENAI_THREAD_ID"]

741message_id = os.environ["OPENAI_MESSAGE_ID"]

742downloads = Path("downloads")

743downloads.mkdir(exist_ok=True)

744 

745# Retrieve the message object

746message = client.beta.threads.messages.retrieve(

747 thread_id=thread_id,

748 message_id=message_id,

749)

750 

751# Extract the message content

752 

753message_content = message.content[0].text

754annotations = message_content.annotations

755citations = []

756 

757# Iterate over the annotations and add footnotes

758 

759for index, annotation in enumerate(annotations):

760 # Replace the text with a footnote.

761 message_content.value = message_content.value.replace(

762 annotation.text, f" [{index}]"

763 )

764 

765 # Gather citations based on annotation attributes

766 if file_citation := getattr(annotation, "file_citation", None):

767 cited_file = client.files.retrieve(file_citation.file_id)

768 citations.append(f"[{index}] {file_citation.quote} from {cited_file.filename}")

769 elif file_path := getattr(annotation, "file_path", None):

770 cited_file = client.files.retrieve(file_path.file_id)

771 file_content = client.files.content(file_path.file_id)

772 output_path = downloads / Path(cited_file.filename).name

773 output_path.write_bytes(file_content.read())

774 citations.append(f"[{index}] Downloaded {output_path}")

775 

776# Add footnotes to the end of the message before displaying to user

777 

778message_content.value += "\n" + "\n".join(citations)

779```

780 

781```go

782message, err := client.Beta.Threads.Messages.Get(context.Background(), "thread_abc123", "msg_abc123")

783if err != nil {

784 panic(err)

785}

786if len(message.Content) == 0 || message.Content[0].Type != "text" {

787 panic("message does not contain text")

788}

789messageContent := message.Content[0].AsText().Text

790citations := make([]string, 0, len(messageContent.Annotations))

791for index, annotation := range messageContent.Annotations {

792 messageContent.Value = strings.ReplaceAll(messageContent.Value, annotation.Text, fmt.Sprintf(" [%d]", index))

793 switch annotation.Type {

794 case "file_citation":

795 citation := annotation.AsFileCitation()

796 file, err := client.Files.Get(context.Background(), citation.FileCitation.FileID)

797 if err != nil {

798 panic(err)

799 }

800 citations = append(citations, fmt.Sprintf("[%d] %s", index, file.Filename))

801 case "file_path":

802 filePath := annotation.AsFilePath()

803 file, err := client.Files.Get(context.Background(), filePath.FilePath.FileID)

804 if err != nil {

805 panic(err)

806 }

807 response, err := client.Files.Content(context.Background(), filePath.FilePath.FileID)

808 if err != nil {

809 panic(err)

810 }

811 defer response.Body.Close()

812 if err := os.MkdirAll("downloads", 0o755); err != nil {

813 panic(err)

814 }

815 outputPath := filepath.Join("downloads", filepath.Base(file.Filename))

816 output, err := os.Create(outputPath)

817 if err != nil {

818 panic(err)

819 }

820 if _, err := io.Copy(output, response.Body); err != nil {

821 output.Close()

822 panic(err)

823 }

824 if err := output.Close(); err != nil {

825 panic(err)

826 }

827 citations = append(citations, fmt.Sprintf("[%d] Downloaded %s", index, outputPath))

828 }

829}

830messageContent.Value += "\n" + strings.Join(citations, "\n")

831fmt.Println(messageContent.Value)

832```

833 

834```java

835import com.openai.client.OpenAIClient;

836import com.openai.client.okhttp.OpenAIOkHttpClient;

837import com.openai.models.beta.threads.messages.MessageRetrieveParams;

838import java.nio.file.Files;

839import java.nio.file.Path;

840import java.nio.file.StandardCopyOption;

841import java.util.ArrayList;

842import java.util.regex.Matcher;

843import java.util.regex.Pattern;

844 

845String messageId = "msg_abc123";

846 

847String threadId = "thread_abc123";

848 

849var message =

850 client

851 .beta()

852 .threads()

853 .messages()

854 .retrieve(messageId, MessageRetrieveParams.builder().threadId(threadId).build());

855 

856var text =

857 message.content().stream()

858 .flatMap(content -> content.text().stream())

859 .findFirst()

860 .orElseThrow(() -> new IllegalStateException("No text content returned"))

861 .text();

862String rendered = text.value();

863var references = new ArrayList<String>();

864for (int index = 0; index < text.annotations().size(); index++) {

865 var annotation = text.annotations().get(index);

866 if (annotation.isFileCitation()) {

867 var citation = annotation.asFileCitation();

868 rendered =

869 rendered.replaceFirst(

870 Pattern.quote(citation.text()), Matcher.quoteReplacement(" [" + index + "]"));

871 var file = client.files().retrieve(citation.fileCitation().fileId());

872 references.add("[" + index + "] " + file.filename());

873 } else if (annotation.isFilePath()) {

874 var filePath = annotation.asFilePath();

875 rendered =

876 rendered.replaceFirst(

877 Pattern.quote(filePath.text()), Matcher.quoteReplacement(" [" + index + "]"));

878 String fileId = filePath.filePath().fileId();

879 var file = client.files().retrieve(fileId);

880 Path downloads = Path.of("downloads");

881 Files.createDirectories(downloads);

882 Path target = downloads.resolve(Path.of(file.filename()).getFileName()).normalize();

883 if (!target.startsWith(downloads)) throw new IllegalArgumentException("Unsafe filename");

884 try (var content = client.files().content(fileId)) {

885 Files.copy(content.body(), target, StandardCopyOption.REPLACE_EXISTING);

886 }

887 references.add("[" + index + "] Downloaded " + target);

888 }

889}

890System.out.println(rendered);

891references.forEach(System.out::println);

892```

893 

894```ruby

895require "openai"

896require "pathname"

897 

898client = OpenAI::Client.new

899message = client.beta.threads.messages.retrieve(

900 "msg_abc123",

901 thread_id: "thread_abc123"

902)

903text_block = message.content.find do |content|

904 content.is_a?(OpenAI::Models::Beta::Threads::TextContentBlock)

905end

906unless text_block.is_a?(OpenAI::Models::Beta::Threads::TextContentBlock)

907 raise "No text content returned"

908end

909text = text_block.text

910downloads = Pathname("downloads")

911references = text.annotations.each_with_index.filter_map do |annotation, index|

912 text.value = text.value.sub(annotation.text, " [#{index}]")

913 

914 case annotation

915 when OpenAI::Models::Beta::Threads::FileCitationAnnotation

916 file = client.files.retrieve(annotation.file_citation.file_id)

917 "[#{index}] #{file.filename}"

918 when OpenAI::Models::Beta::Threads::FilePathAnnotation

919 file_id = annotation.file_path.file_id

920 file = client.files.retrieve(file_id)

921 downloads.mkpath

922 output_path = downloads.join(Pathname(file.filename).basename)

923 output_path.binwrite(client.files.content(file_id).read)

924 "[#{index}] Downloaded #{output_path}"

925 end

926end

927 

928puts(([text.value] + references).join("\n"))

929```

930 

931 

932## Runs and Run Steps

933 

934When you have all the context you need from your user in the Thread, you can run the Thread with an Assistant of your choice.

935 

936```javascript

937const run = await openai.beta.threads.runs.create(thread.id, {

938 assistant_id: assistant.id,

939});

940```

941 

942```python

943run = client.beta.threads.runs.create(

944 thread_id=thread.id,

945 assistant_id=assistant.id,

946)

947```

948 

949```go

950_, err := client.Beta.Threads.Runs.New(context.Background(), "thread_abc123", openai.BetaThreadRunNewParams{

951 AssistantID: "asst_ToSF7Gb04YMj8AMMm50ZLLtY",

952})

953if err != nil {

954 panic(err)

955}

956```

957 

958```java

959import com.openai.client.OpenAIClient;

960import com.openai.client.okhttp.OpenAIOkHttpClient;

961import com.openai.models.beta.threads.runs.RunCreateParams;

962 

963String threadId = "thread_abc123";

964 

965String assistantId = "asst_ToSF7Gb04YMj8AMMm50ZLLtY";

966 

967var run =

968 client

969 .beta()

970 .threads()

971 .runs()

972 .create(threadId, RunCreateParams.builder().assistantId(assistantId).build());

973 

974System.out.println(run.status());

975```

976 

977```ruby

978require "openai"

979 

980client = OpenAI::Client.new

981run = client.beta.threads.runs.create("thread_abc123", assistant_id: "asst_ToSF7Gb04YMj8AMMm50ZLLtY")

982puts(run.id)

983```

984 

985```bash

986curl https://api.openai.com/v1/threads/THREAD_ID/runs \

987 -H "Authorization: Bearer $OPENAI_API_KEY" \

988 -H "Content-Type: application/json" \

989 -H "OpenAI-Beta: assistants=v2" \

990 -d '{

991 "assistant_id": "asst_ToSF7Gb04YMj8AMMm50ZLLtY"

992 }'

993```

994 

995 

996By default, a Run will use the `model` and `tools` configuration specified in Assistant object, but you can override most of these when creating the Run for added flexibility:

997 

998```javascript

999const run = await openai.beta.threads.runs.create(thread.id, {

1000 assistant_id: assistant.id,

1001 model: "gpt-4o",

1002 instructions: "New instructions that override the Assistant instructions",

1003 tools: [{ type: "code_interpreter" }, { type: "file_search" }],

1004});

1005```

1006 

1007```python

1008run = client.beta.threads.runs.create(

1009 thread_id=thread.id,

1010 assistant_id=assistant.id,

1011 model="gpt-4o",

1012 instructions="New instructions that override the Assistant instructions",

1013 tools=[{"type": "code_interpreter"}, {"type": "file_search"}],

1014)

1015```

1016 

1017```go

1018_, err := client.Beta.Threads.Runs.New(context.Background(), "thread_abc123", openai.BetaThreadRunNewParams{

1019 AssistantID: "asst_ToSF7Gb04YMj8AMMm50ZLLtY",

1020 Model: shared.ChatModelGPT4o,

1021 Instructions: openai.String("New instructions that override the Assistant instructions"),

1022 Tools: []openai.AssistantToolUnionParam{

1023 {OfCodeInterpreter: &openai.CodeInterpreterToolParam{}},

1024 {OfFileSearch: &openai.FileSearchToolParam{}},

1025 },

1026})

1027if err != nil {

1028 panic(err)

1029}

1030```

1031 

1032```java

1033import com.openai.client.OpenAIClient;

1034import com.openai.client.okhttp.OpenAIOkHttpClient;

1035import com.openai.models.beta.assistants.CodeInterpreterTool;

1036import com.openai.models.beta.assistants.FileSearchTool;

1037import com.openai.models.beta.threads.runs.RunCreateParams;

1038 

1039String threadId = "thread_abc123";

1040 

1041String assistantId = "asst_ToSF7Gb04YMj8AMMm50ZLLtY";

1042 

1043var run =

1044 client

1045 .beta()

1046 .threads()

1047 .runs()

1048 .create(

1049 threadId,

1050 RunCreateParams.builder()

1051 .assistantId(assistantId)

1052 .model("gpt-4o")

1053 .instructions("New instructions that override the Assistant instructions")

1054 .addTool(CodeInterpreterTool.builder().build())

1055 .addTool(FileSearchTool.builder().build())

1056 .build());

1057 

1058System.out.println(run.status());

1059```

1060 

1061```ruby

1062require "openai"

1063 

1064client = OpenAI::Client.new

1065run = client.beta.threads.runs.create(

1066 "thread_abc123",

1067 assistant_id: "asst_ToSF7Gb04YMj8AMMm50ZLLtY",

1068 model: "gpt-4o",

1069 instructions: "New instructions that override the Assistant instructions",

1070 tools: [{type: :code_interpreter}, {type: :file_search}]

1071)

1072puts(run.id)

1073```

1074 

1075```bash

1076curl https://api.openai.com/v1/threads/THREAD_ID/runs \

1077 -H "Authorization: Bearer $OPENAI_API_KEY" \

1078 -H "Content-Type: application/json" \

1079 -H "OpenAI-Beta: assistants=v2" \

1080 -d '{

1081 "assistant_id": "ASSISTANT_ID",

1082 "model": "gpt-4o",

1083 "instructions": "New instructions that override the Assistant instructions",

1084 "tools": [{"type": "code_interpreter"}, {"type": "file_search"}]

1085 }'

1086```

1087 

1088 

1089Note: `tool_resources` associated with the Assistant cannot be overridden during Run creation. You must use the [modify Assistant](https://developers.openai.com/api/reference/resources/beta/subresources/assistants/methods/update) endpoint to do this.

1090 

1091#### Run lifecycle

1092 

1093Run objects can have multiple statuses.

1094 

1095![Run lifecycle - diagram showing possible status transitions](https://cdn.openai.com/API/docs/images/diagram-run-statuses-v2.png)

1096 

1097| Status | Definition |

1098| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1099| `queued` | When Runs are first created or when you complete the `required_action`, they are moved to a queued status. They should almost immediately move to `in_progress`. |

1100| `in_progress` | While `in_progress`, the Assistant uses the model and tools to perform steps. You can view progress being made by the Run by examining the [Run Steps](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/runs/subresources/steps). |

1101| `completed` | The Run successfully completed! You can now view all Messages the Assistant added to the Thread, and all the steps the Run took. You can also continue the conversation by adding more user Messages to the Thread and creating another Run. |

1102| `requires_action` | When using the [Function calling](https://developers.openai.com/api/docs/assistants/tools/function-calling) tool, the Run will move to a `required_action` state once the model determines the names and arguments of the functions to be called. You must then run those functions and [submit the outputs](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/runs/methods/submit_tool_outputs) before the run proceeds. If the outputs are not provided before the `expires_at` timestamp passes (roughly 10 mins past creation), the run will move to an expired status. |

1103| `expired` | This happens when the function calling outputs were not submitted before `expires_at` and the run expires. Additionally, if the runs take too long to execute and go beyond the time stated in `expires_at`, our systems will expire the run. |

1104| `cancelling` | You can attempt to cancel an `in_progress` run using the [Cancel Run](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/runs/methods/cancel) endpoint. Once the attempt to cancel succeeds, status of the Run moves to `cancelled`. Cancellation is attempted but not guaranteed. |

1105| `cancelled` | Run was successfully cancelled. |

1106| `failed` | You can view the reason for the failure by looking at the `last_error` object in the Run. The timestamp for the failure will be recorded under `failed_at`. |

1107| `incomplete` | Run ended due to `max_prompt_tokens` or `max_completion_tokens` reached. You can view the specific reason by looking at the `incomplete_details` object in the Run. |

1108 

1109#### Polling for updates

1110 

1111If you are not using [streaming](https://developers.openai.com/api/docs/assistants/migration#step-4-create-a-run?context=with-streaming), in order to keep the status of your run up to date, you will have to periodically [retrieve the Run](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/runs/methods/retrieve) object. You can check the status of the run each time you retrieve the object to determine what your application should do next.

1112 

1113You can optionally use Polling Helpers in our [Node](https://github.com/openai/openai-node?tab=readme-ov-file#polling-helpers) and [Python](https://github.com/openai/openai-python?tab=readme-ov-file#polling-helpers) SDKs to help you with this. These helpers will automatically poll the Run object for you and return the Run object when it's in a terminal state.

1114 

1115#### Thread locks

1116 

1117When a Run is `in_progress` and not in a terminal state, the Thread is locked. This means that:

1118 

1119- New Messages cannot be added to the Thread.

1120- New Runs cannot be created on the Thread.

1121 

1122#### Run steps

1123 

1124![Run steps lifecycle - diagram showing possible status transitions](https://cdn.openai.com/API/docs/images/diagram-2.png)

1125 

1126Run step statuses have the same meaning as Run statuses.

1127 

1128Most of the interesting detail in the Run Step object lives in the `step_details` field. There can be two types of step details:

1129 

11301. `message_creation`: This Run Step is created when the Assistant creates a Message on the Thread.

11312. `tool_calls`: This Run Step is created when the Assistant calls a tool. Details around this are covered in the relevant sections of the [Tools](https://developers.openai.com/api/docs/assistants/tools) guide.

1132 

1133## Data Access Guidance

1134 

1135Currently, Assistants, Threads, Messages, and Vector Stores created via the API are scoped to the Project they're created in. As such, any person with API key access to that Project is able to read or write Assistants, Threads, Messages, and Runs in the Project.

1136 

1137We strongly recommend the following data access controls:

1138 

1139- _Implement authorization._ Before performing reads or writes on Assistants, Threads, Messages, and Vector Stores, ensure that the end-user is authorized to do so. For example, store in your database the object IDs that the end-user has access to, and check it before fetching the object ID with the API.

1140- _Restrict API key access._ Carefully consider who in your organization should have API keys and be part of a Project. Periodically audit this list. API keys enable a wide range of operations including reading and modifying sensitive information, such as Messages and Files.

1141- _Create separate accounts._ Consider creating separate Projects for different applications in order to isolate data across multiple applications.

1# Assistants API tools

2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 

5After achieving feature parity in the Responses API, we've deprecated the Assistants API. It will shut down on August 26, 2026. Follow the [migration guide](https://developers.openai.com/platform/assistants/migration) to update your integration. [Learn more](https://platform.openai.com/docs/guides/migrate-to-responses).

6 

7## Overview

8 

9Assistants created using the Assistants API can be equipped with tools that allow them to perform more complex tasks or interact with your application.

10We provide built-in tools for assistants, but you can also define your own tools to extend their capabilities using Function Calling.

11 

12The Assistants API currently supports the following tools:

13 

14 

15 

16File Search

17 

18 

19 

20 Built-in RAG tool to process and search through files

21 

22 

23 

24 

25Code Interpreter

26 

27 

28 

29 Write and run python code, process files and diverse data

30 

31 

32 

33 

34Function Calling

35 

36 

37 

38 Use your own custom functions to interact with your application

39 

40 

41 

42## Next steps

43 

44- See the API reference to [submit tool outputs](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/runs/methods/submit_tool_outputs)

45- Build a tool-using assistant with our [Quickstart app](https://github.com/openai/openai-assistants-quickstart)

1# Assistants Code Interpreter

2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 

5After achieving feature parity in the Responses API, we've deprecated the Assistants API. It will shut down on August 26, 2026. Follow the [migration guide](https://developers.openai.com/platform/assistants/migration) to update your integration. [Learn more](https://platform.openai.com/docs/guides/migrate-to-responses).

6 

7## Overview

8 

9Code Interpreter allows Assistants to write and run Python code in a sandboxed execution environment. This tool can process files with diverse data and formatting, and generate files with data and images of graphs. Code Interpreter allows your Assistant to run code iteratively to solve challenging code and math problems. When your Assistant writes code that fails to run, it can iterate on this code by attempting to run different code until the code execution succeeds.

10 

11See a quickstart of how to get started with Code Interpreter [here](https://developers.openai.com/api/docs/assistants/migration#step-1-create-an-assistant?context=with-streaming).

12 

13## How it works

14 

15Code Interpreter is charged at $0.03 per session. If your Assistant calls Code Interpreter simultaneously in two different threads (e.g., one thread per end-user), two Code Interpreter sessions are created. Each session is active by default for one hour, which means that you only pay for one session per if users interact with Code Interpreter in the same thread for up to one hour.

16 

17### Enabling Code Interpreter

18 

19Pass `code_interpreter` in the `tools` parameter of the Assistant object to enable Code Interpreter:

20 

21```javascript

22const assistant = await openai.beta.assistants.create({

23 instructions:

24 "You are a personal math tutor. When asked a math question, write and run code to answer the question.",

25 model: "gpt-4o",

26 tools: [{ type: "code_interpreter" }],

27});

28```

29 

30```python

31assistant = client.beta.assistants.create(

32 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

33 model="gpt-4o",

34 tools=[{"type": "code_interpreter"}],

35)

36```

37 

38```go

39assistant, err := client.Beta.Assistants.New(context.Background(), openai.BetaAssistantNewParams{

40 Instructions: openai.String("You are a personal math tutor. When asked a math question, write and run code to answer the question."),

41 Model: shared.ChatModelGPT4o,

42 Tools: []openai.AssistantToolUnionParam{{OfCodeInterpreter: &openai.CodeInterpreterToolParam{}}},

43})

44if err != nil {

45 panic(err)

46}

47```

48 

49```java

50import com.openai.client.OpenAIClient;

51import com.openai.client.okhttp.OpenAIOkHttpClient;

52import com.openai.models.beta.assistants.AssistantCreateParams;

53import com.openai.models.beta.assistants.CodeInterpreterTool;

54 

55var assistant =

56 client

57 .beta()

58 .assistants()

59 .create(

60 AssistantCreateParams.builder()

61 .model("gpt-4o")

62 .instructions(

63 "You are a personal math tutor. When asked a math question, write and run"

64 + " code to answer the question.")

65 .addTool(CodeInterpreterTool.builder().build())

66 .build());

67 

68System.out.println(assistant.id());

69```

70 

71```ruby

72require "openai"

73 

74client = OpenAI::Client.new

75assistant = client.beta.assistants.create(

76 model: "gpt-4o",

77 tools: [{type: :code_interpreter}]

78)

79puts(assistant.id)

80```

81 

82```bash

83curl https://api.openai.com/v1/assistants \

84 -u :$OPENAI_API_KEY \

85 -H 'Content-Type: application/json' \

86 -H 'OpenAI-Beta: assistants=v2' \

87 -d '{

88 "instructions": "You are a personal math tutor. When asked a math question, write and run code to answer the question.",

89 "tools": [

90 { "type": "code_interpreter" }

91 ],

92 "model": "gpt-4o"

93 }'

94```

95 

96 

97The model then decides when to invoke Code Interpreter in a Run based on the nature of the user request. This behavior can be promoted by prompting in the Assistant's `instructions` (e.g., “write code to solve this problem”).

98 

99### Passing files to Code Interpreter

100 

101Files that are passed at the Assistant level are accessible by all Runs with this Assistant:

102 

103```javascript

104// Upload a file with an "assistants" purpose

105const file = await openai.files.create({

106 file: fs.createReadStream("mydata.csv"),

107 purpose: "assistants",

108});

109 

110// Create an assistant using the file ID

111const assistant = await openai.beta.assistants.create({

112 instructions:

113 "You are a personal math tutor. When asked a math question, write and run code to answer the question.",

114 model: "gpt-4o",

115 tools: [{ type: "code_interpreter" }],

116 tool_resources: {

117 code_interpreter: {

118 file_ids: [file.id],

119 },

120 },

121});

122```

123 

124```python

125# Upload a file with an "assistants" purpose

126file = client.files.create(file=open("mydata.csv", "rb"), purpose="assistants")

127 

128# Create an assistant using the file ID

129assistant = client.beta.assistants.create(

130 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

131 model="gpt-4o",

132 tools=[{"type": "code_interpreter"}],

133 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

134)

135```

136 

137```go

138input, err := os.Open("mydata.csv")

139if err != nil {

140 panic(err)

141}

142defer input.Close()

143file, err := client.Files.New(context.Background(), openai.FileNewParams{

144 File: input,

145 Purpose: openai.FilePurposeAssistants,

146})

147if err != nil {

148 panic(err)

149}

150assistant, err := client.Beta.Assistants.New(context.Background(), openai.BetaAssistantNewParams{

151 Instructions: openai.String("You are a personal math tutor. When asked a math question, write and run code to answer the question."),

152 Model: shared.ChatModelGPT4o,

153 Tools: []openai.AssistantToolUnionParam{{OfCodeInterpreter: &openai.CodeInterpreterToolParam{}}},

154 ToolResources: openai.BetaAssistantNewParamsToolResources{

155 CodeInterpreter: openai.BetaAssistantNewParamsToolResourcesCodeInterpreter{FileIDs: []string{file.ID}},

156 },

157})

158if err != nil {

159 panic(err)

160}

161```

162 

163```java

164import com.openai.client.OpenAIClient;

165import com.openai.client.okhttp.OpenAIOkHttpClient;

166import com.openai.models.beta.assistants.AssistantCreateParams;

167import com.openai.models.beta.assistants.CodeInterpreterTool;

168import com.openai.models.files.FileCreateParams;

169import com.openai.models.files.FilePurpose;

170import java.nio.file.Path;

171 

172var file =

173 client

174 .files()

175 .create(

176 FileCreateParams.builder()

177 .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))

178 .purpose(FilePurpose.ASSISTANTS)

179 .build());

180var assistant =

181 client

182 .beta()

183 .assistants()

184 .create(

185 AssistantCreateParams.builder()

186 .model("gpt-4o")

187 .instructions("When asked a math question, write and run code to answer it.")

188 .addTool(CodeInterpreterTool.builder().build())

189 .toolResources(

190 AssistantCreateParams.ToolResources.builder()

191 .codeInterpreter(

192 AssistantCreateParams.ToolResources.CodeInterpreter.builder()

193 .addFileId(file.id())

194 .build())

195 .build())

196 .build());

197System.out.println(assistant.id());

198```

199 

200```ruby

201require "openai"

202require "pathname"

203 

204client = OpenAI::Client.new

205file = client.files.create(

206 file: Pathname("revenue-forecast.csv"),

207 purpose: :assistants

208)

209assistant = client.beta.assistants.create(

210 model: "gpt-4o",

211 instructions: "When asked a math question, write and run code to answer it.",

212 tools: [{type: :code_interpreter}],

213 tool_resources: {

214 code_interpreter: {file_ids: [file.id]}

215 }

216)

217puts(assistant.id)

218```

219 

220```bash

221# Upload a file with an "assistants" purpose

222curl https://api.openai.com/v1/files \

223 -H "Authorization: Bearer $OPENAI_API_KEY" \

224 -F purpose="assistants" \

225 -F file="@/path/to/mydata.csv"

226 

227# Create an assistant using the file ID

228curl https://api.openai.com/v1/assistants \

229 -u :$OPENAI_API_KEY \

230 -H 'Content-Type: application/json' \

231 -H 'OpenAI-Beta: assistants=v2' \

232 -d '{

233 "instructions": "You are a personal math tutor. When asked a math question, write and run code to answer the question.",

234 "tools": [{"type": "code_interpreter"}],

235 "model": "gpt-4o",

236 "tool_resources": {

237 "code_interpreter": {

238 "file_ids": ["file-BK7bzQj3FfZFXr7DbL6xJwfo"]

239 }

240 }

241 }'

242```

243 

244 

245Files can also be passed at the Thread level. These files are only accessible in the specific Thread. Upload the File using the [File upload](https://developers.openai.com/api/reference/resources/files/methods/create) endpoint and then pass the File ID as part of the Message creation request:

246 

247```javascript

248const thread = await openai.beta.threads.create({

249 messages: [

250 {

251 role: "user",

252 content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",

253 attachments: [

254 {

255 file_id: file.id,

256 tools: [{ type: "code_interpreter" }],

257 },

258 ],

259 },

260 ],

261});

262```

263 

264```python

265thread = client.beta.threads.create(

266 messages=[

267 {

268 "role": "user",

269 "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",

270 "attachments": [

271 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

272 ],

273 }

274 ]

275)

276```

277 

278```go

279thread, err := client.Beta.Threads.New(context.Background(), openai.BetaThreadNewParams{

280 Messages: []openai.BetaThreadNewParamsMessage{{

281 Role: "user",

282 Content: openai.BetaThreadNewParamsMessageContentUnion{OfString: openai.String("I need to solve the equation `3x + 11 = 14`. Can you help me?")},

283 Attachments: []openai.BetaThreadNewParamsMessageAttachment{{

284 FileID: openai.String("file-ACq8OjcLQm2eIG0BvRM4z5qX"),

285 Tools: []openai.BetaThreadNewParamsMessageAttachmentToolUnion{{OfCodeInterpreter: &openai.CodeInterpreterToolParam{}}},

286 }},

287 }},

288})

289if err != nil {

290 panic(err)

291}

292```

293 

294```java

295import com.openai.client.OpenAIClient;

296import com.openai.client.okhttp.OpenAIOkHttpClient;

297import com.openai.models.beta.assistants.CodeInterpreterTool;

298import com.openai.models.beta.threads.ThreadCreateParams;

299 

300String fileId = "file-ACq8OjcLQm2eIG0BvRM4z5qX";

301 

302var thread =

303 client

304 .beta()

305 .threads()

306 .create(

307 ThreadCreateParams.builder()

308 .addMessage(

309 ThreadCreateParams.Message.builder()

310 .role(ThreadCreateParams.Message.Role.USER)

311 .content(

312 "I need to solve the equation `3x + 11 = 14`. Can you help me?")

313 .addAttachment(

314 ThreadCreateParams.Message.Attachment.builder()

315 .fileId(fileId)

316 .addTool(CodeInterpreterTool.builder().build())

317 .build())

318 .build())

319 .build());

320 

321System.out.println(thread.id());

322```

323 

324```ruby

325require "openai"

326 

327client = OpenAI::Client.new

328thread = client.beta.threads.create(

329 messages: [{

330 role: :user,

331 content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",

332 attachments: [{

333 file_id: "file-ACq8OjcLQm2eIG0BvRM4z5qX",

334 tools: [{type: :code_interpreter}]

335 }]

336 }]

337)

338puts(thread.id)

339```

340 

341```bash

342curl https://api.openai.com/v1/threads/thread_abc123/messages \

343 -u :$OPENAI_API_KEY \

344 -H 'Content-Type: application/json' \

345 -H 'OpenAI-Beta: assistants=v2' \

346 -d '{

347 "role": "user",

348 "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",

349 "attachments": [

350 {

351 "file_id": "file-ACq8OjcLQm2eIG0BvRM4z5qX",

352 "tools": [{"type": "code_interpreter"}]

353 }

354 ]

355 }'

356```

357 

358 

359Files have a maximum size of 512 MB. Code Interpreter supports a variety of file formats including `.csv`, `.pdf`, `.json` and many more. More details on the file extensions (and their corresponding MIME-types) supported can be found in the [Supported files](#supported-files) section below.

360 

361### Reading images and files generated by Code Interpreter

362 

363Code Interpreter in the API also outputs files, such as generating image diagrams, CSVs, and PDFs. There are two types of files that are generated:

364 

3651. Images

3662. Data files (e.g. a `csv` file with data generated by the Assistant)

367 

368When Code Interpreter generates an image, you can look up and download this file in the `file_id` field of the Assistant Message response:

369 

370```json

371{

372 "id": "msg_abc123",

373 "object": "thread.message",

374 "created_at": 1698964262,

375 "thread_id": "thread_abc123",

376 "role": "assistant",

377 "content": [

378 {

379 "type": "image_file",

380 "image_file": {

381 "file_id": "file-abc123"

382 }

383 }

384 ]

385 # ...

386}

387```

388 

389The file content can then be downloaded by passing the file ID to the Files API:

390 

391```javascript

392import fs from "fs";

393import OpenAI from "openai";

394 

395const openai = new OpenAI();

396 

397async function main() {

398 const response = await openai.files.content("file-abc123");

399 

400 // Extract the binary data from the Response object

401 const image_data = await response.arrayBuffer();

402 

403 // Convert the binary data to a Buffer

404 const image_data_buffer = Buffer.from(image_data);

405 

406 // Save the image to a specific location

407 fs.writeFileSync("./my-image.png", image_data_buffer);

408}

409 

410main();

411```

412 

413```python

414import os

415 

416from openai import OpenAI

417 

418file_id = os.environ["OPENAI_FILE_ID"]

419client = OpenAI()

420 

421image_data = client.files.content(file_id)

422image_data_bytes = image_data.read()

423 

424with open("./my-image.png", "wb") as file:

425 file.write(image_data_bytes)

426```

427 

428```go

429response, err := client.Files.Content(context.Background(), "file-abc123")

430if err != nil {

431 panic(err)

432}

433defer response.Body.Close()

434output, err := os.Create("./my-image.png")

435if err != nil {

436 panic(err)

437}

438if _, err := io.Copy(output, response.Body); err != nil {

439 output.Close()

440 panic(err)

441}

442if err := output.Close(); err != nil {

443 panic(err)

444}

445```

446 

447```java

448import com.openai.client.OpenAIClient;

449import com.openai.client.okhttp.OpenAIOkHttpClient;

450import com.openai.core.http.HttpResponse;

451import java.io.IOException;

452import java.nio.file.Files;

453import java.nio.file.Path;

454import java.nio.file.StandardCopyOption;

455 

456String fileId = "file-abc123";

457 

458try (HttpResponse content = client.files().content(fileId)) {

459 Files.copy(content.body(), Path.of("my-image.png"), StandardCopyOption.REPLACE_EXISTING);

460}

461```

462 

463```ruby

464require "openai"

465 

466client = OpenAI::Client.new

467image = client.files.content("file-abc123")

468File.binwrite("my-image.png", image.read)

469```

470 

471```bash

472curl https://api.openai.com/v1/files/file-abc123/content \

473 -H "Authorization: Bearer $OPENAI_API_KEY" \

474 --output image.png

475```

476 

477 

478When Code Interpreter references a file path (e.g., ”Download this csv file”), file paths are listed as annotations. You can convert these annotations into links to download the file:

479 

480```json

481{

482 "id": "msg_abc123",

483 "object": "thread.message",

484 "created_at": 1699073585,

485 "thread_id": "thread_abc123",

486 "role": "assistant",

487 "content": [

488 {

489 "type": "text",

490 "text": {

491 "value": "The rows of the CSV file have been shuffled and saved to a new CSV file. You can download the shuffled CSV file from the following link:\\n\\n[Download Shuffled CSV File](sandbox:/mnt/data/shuffled_file.csv)",

492 "annotations": [

493 {

494 "type": "file_path",

495 "text": "sandbox:/mnt/data/shuffled_file.csv",

496 "start_index": 167,

497 "end_index": 202,

498 "file_path": {

499 "file_id": "file-abc123"

500 }

501 }

502 ...

503```

504 

505### Input and output logs of Code Interpreter

506 

507By listing the steps of a Run that called Code Interpreter, you can inspect the code `input` and `outputs` logs of Code Interpreter:

508 

509```javascript

510const runSteps = await openai.beta.threads.runs.steps.list(run.id, {

511 thread_id: thread.id,

512});

513```

514 

515```python

516import os

517 

518thread_id = os.environ["OPENAI_THREAD_ID"]

519run_id = os.environ["OPENAI_RUN_ID"]

520 

521run_steps = client.beta.threads.runs.steps.list(

522 thread_id=thread_id,

523 run_id=run_id,

524)

525```

526 

527```go

528runSteps, err := client.Beta.Threads.Runs.Steps.List(context.Background(), "thread_abc123", "run_abc123", openai.BetaThreadRunStepListParams{})

529if err != nil {

530 panic(err)

531}

532fmt.Println(runSteps.Data)

533```

534 

535```ruby

536require "openai"

537 

538client = OpenAI::Client.new

539steps = client.beta.threads.runs.steps.list(

540 "run_abc123",

541 thread_id: "thread_abc123"

542)

543puts(steps.data)

544```

545 

546```bash

547curl https://api.openai.com/v1/threads/thread_abc123/runs/RUN_ID/steps \

548 -H "Authorization: Bearer $OPENAI_API_KEY" \

549 -H "OpenAI-Beta: assistants=v2" \

550```

551 

552 

553```bash

554{

555 "object": "list",

556 "data": [

557 {

558 "id": "step_abc123",

559 "object": "thread.run.step",

560 "type": "tool_calls",

561 "run_id": "run_abc123",

562 "thread_id": "thread_abc123",

563 "status": "completed",

564 "step_details": {

565 "type": "tool_calls",

566 "tool_calls": [

567 {

568 "type": "code",

569 "code": {

570 "input": "# Calculating 2 + 2\\nresult = 2 + 2\\nresult",

571 "outputs": [

572 {

573 "type": "logs",

574 "logs": "4"

575 }

576 ...

577 }

578```

579 

580## Supported files

581 

582| File format | MIME type |

583| ----------- | --------------------------------------------------------------------------- |

584| `.c` | `text/x-c` |

585| `.cs` | `text/x-csharp` |

586| `.cpp` | `text/x-c++` |

587| `.csv` | `text/csv` |

588| `.doc` | `application/msword` |

589| `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |

590| `.html` | `text/html` |

591| `.java` | `text/x-java` |

592| `.json` | `application/json` |

593| `.md` | `text/markdown` |

594| `.pdf` | `application/pdf` |

595| `.php` | `text/x-php` |

596| `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |

597| `.py` | `text/x-python` |

598| `.py` | `text/x-script.python` |

599| `.rb` | `text/x-ruby` |

600| `.tex` | `text/x-tex` |

601| `.txt` | `text/plain` |

602| `.css` | `text/css` |

603| `.js` | `text/javascript` |

604| `.sh` | `application/x-sh` |

605| `.ts` | `application/typescript` |

606| `.csv` | `application/csv` |

607| `.jpeg` | `image/jpeg` |

608| `.jpg` | `image/jpeg` |

609| `.gif` | `image/gif` |

610| `.pkl` | `application/octet-stream` |

611| `.png` | `image/png` |

612| `.tar` | `application/x-tar` |

613| `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |

614| `.xml` | `application/xml or "text/xml"` |

615| `.zip` | `application/zip` |

1# Assistants File Search

2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 

5After achieving feature parity in the Responses API, we've deprecated the Assistants API. It will shut down on August 26, 2026. Follow the [migration guide](https://developers.openai.com/platform/assistants/migration) to update your integration. [Learn more](https://platform.openai.com/docs/guides/migrate-to-responses).

6 

7## Overview

8 

9File Search augments the Assistant with knowledge from outside its model, such as proprietary product information or documents provided by your users. OpenAI automatically parses and chunks your documents, creates and stores the embeddings, and use both vector and keyword search to retrieve relevant content to answer user queries.

10 

11## Quickstart

12 

13In this example, we’ll create an assistant that can help answer questions about companies’ financial statements.

14 

15### Step 1: Create a new Assistant with File Search Enabled

16 

17Create a new assistant with `file_search` enabled in the `tools` parameter of the Assistant.

18 

19```javascript

20import OpenAI from "openai";

21const openai = new OpenAI();

22 

23async function main() {

24 const assistant = await openai.beta.assistants.create({

25 name: "Financial Analyst Assistant",

26 instructions:

27 "You are an expert financial analyst. Use you knowledge base to answer questions about audited financial statements.",

28 model: "gpt-4o",

29 tools: [{ type: "file_search" }],

30 });

31}

32 

33main();

34```

35 

36```python

37from openai import OpenAI

38 

39client = OpenAI()

40 

41assistant = client.beta.assistants.create(

42 name="Financial Analyst Assistant",

43 instructions="You are an expert financial analyst. Use you knowledge base to answer questions about audited financial statements.",

44 model="gpt-4o",

45 tools=[{"type": "file_search"}],

46)

47```