Files

List files

files.list(**kwargs) -> CursorPage<FileObject>

get /files

List files

Parameters

after: String

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
limit: Integer

A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.
order: :asc | :desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
- :asc
- :desc
purpose: String

Only return files with the given purpose.

Returns

class FileObject

The File object represents a document that has been uploaded to OpenAI.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - :assistants
  - :assistants_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

page = openai.files.list

puts(page)

Response

{
  "data": [
    {
      "id": "id",
      "bytes": 0,
      "created_at": 0,
      "filename": "filename",
      "object": "file",
      "purpose": "assistants",
      "status": "uploaded",
      "expires_at": 0,
      "status_details": "status_details"
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}

Upload file

files.create(**kwargs) -> FileObject

post /files

Upload file

Parameters

file: String

The File object (not file name) to be uploaded.
purpose: untyped
expires_after: ExpiresAfter{ anchor, seconds}

The expiration policy for a file. By default, files with purpose=batch expire after 30 days and all other files are persisted until they are manually deleted.
- anchor: :created_at
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: created_at.
  - :created_at
- seconds: Integer
  
  The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

class FileObject

The File object represents a document that has been uploaded to OpenAI.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - :assistants
  - :assistants_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

file_object = openai.files.create(file: StringIO.new("Example data"), purpose: {})

puts(file_object)

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "filename": "filename",
  "object": "file",
  "purpose": "assistants",
  "status": "uploaded",
  "expires_at": 0,
  "status_details": "status_details"
}

Delete file

files.delete(file_id) -> FileDeleted

delete /files/{file_id}

Delete file

Parameters

file_id: String

Returns

class FileDeleted
- id: String
- deleted: bool
- object: :file
  - :file

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

file_deleted = openai.files.delete("file_id")

puts(file_deleted)

Response

{
  "id": "id",
  "deleted": true,
  "object": "file"
}

Retrieve file

files.retrieve(file_id) -> FileObject

get /files/{file_id}

Retrieve file

Parameters

file_id: String

Returns

class FileObject

The File object represents a document that has been uploaded to OpenAI.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - :assistants
  - :assistants_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

file_object = openai.files.retrieve("file_id")

puts(file_object)

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "filename": "filename",
  "object": "file",
  "purpose": "assistants",
  "status": "uploaded",
  "expires_at": 0,
  "status_details": "status_details"
}

Retrieve file content

files.content(file_id) -> StringIO

get /files/{file_id}/content

Retrieve file content

Parameters

file_id: String

Returns

StringIO

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

response = openai.files.content("file_id")

puts(response)

Domain Types

File Content

FileContent = String

File Deleted

class FileDeleted
- id: String
- deleted: bool
- object: :file
  - :file

File Object

class FileObject

The File object represents a document that has been uploaded to OpenAI.
- id: String
  
  The file identifier, which can be referenced in the API endpoints.
- bytes: Integer
  
  The size of the file, in bytes.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the file was created.
- filename: String
  
  The name of the file.
- object: :file
  
  The object type, which is always file.
  - :file
- purpose: :assistants | :assistants_output | :batch | 5 more
  
  The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
  - :assistants
  - :assistants_output
  - :batch
  - :batch_output
  - :"fine-tune"
  - :"fine-tune-results"
  - :vision
  - :user_data
- status: :uploaded | :processed | :error
  
  Deprecated. The current status of the file, which can be either uploaded, processed, or error.
  - :uploaded
  - :processed
  - :error
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the file will expire.
- status_details: String
  
  Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

File Purpose

FilePurpose = untyped

ruby/resources/files/index.md +525 −0 created

1# Files

3## List files

5`files.list(**kwargs) -> CursorPage<FileObject>`

7**get** `/files`

9List files

11### Parameters

13- `after: String`

15 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

17- `limit: Integer`

19 A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.

21- `order: :asc | :desc`

23 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

25 - `:asc`

27 - `:desc`

29- `purpose: String`

31 Only return files with the given purpose.

33### Returns

35- `class FileObject`

37 The `File` object represents a document that has been uploaded to OpenAI.

39 - `id: String`

41 The file identifier, which can be referenced in the API endpoints.

43 - `bytes: Integer`

45 The size of the file, in bytes.

47 - `created_at: Integer`

49 The Unix timestamp (in seconds) for when the file was created.

51 - `filename: String`

53 The name of the file.

55 - `object: :file`

57 The object type, which is always `file`.

59 - `:file`

61 - `purpose: :assistants | :assistants_output | :batch | 5 more`

63 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

65 - `:assistants`

67 - `:assistants_output`

69 - `:batch`

71 - `:batch_output`

73 - `:"fine-tune"`

75 - `:"fine-tune-results"`

77 - `:vision`

79 - `:user_data`

81 - `status: :uploaded | :processed | :error`

83 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

85 - `:uploaded`

87 - `:processed`

89 - `:error`

91 - `expires_at: Integer`

93 The Unix timestamp (in seconds) for when the file will expire.

95 - `status_details: String`

97 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

99### Example

100

101```ruby

102require "openai"

103

104openai = OpenAI::Client.new(api_key: "My API Key")

105

106page = openai.files.list

107

108puts(page)

109```

110

111#### Response

112

113```json

114{

115 "data": [

116 {

117 "id": "id",

118 "bytes": 0,

119 "created_at": 0,

120 "filename": "filename",

121 "object": "file",

122 "purpose": "assistants",

123 "status": "uploaded",

124 "expires_at": 0,

125 "status_details": "status_details"

126 }

127 ],

128 "first_id": "file-abc123",

129 "has_more": false,

130 "last_id": "file-abc456",

131 "object": "list"

132}

133```

134

135## Upload file

136

137`files.create(**kwargs) -> FileObject`

138

139**post** `/files`

140

141Upload file

142

143### Parameters

144

145- `file: String`

146

147 The File object (not file name) to be uploaded.

148

149- `purpose: untyped`

150

151- `expires_after: ExpiresAfter{ anchor, seconds}`

152

153 The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.

154

155 - `anchor: :created_at`

156

157 Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.

158

159 - `:created_at`

160

161 - `seconds: Integer`

162

163 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

164

165### Returns

166

167- `class FileObject`

168

169 The `File` object represents a document that has been uploaded to OpenAI.

170

171 - `id: String`

172

173 The file identifier, which can be referenced in the API endpoints.

174

175 - `bytes: Integer`

176

177 The size of the file, in bytes.

178

179 - `created_at: Integer`

180

181 The Unix timestamp (in seconds) for when the file was created.

182

183 - `filename: String`

184

185 The name of the file.

186

187 - `object: :file`

188

189 The object type, which is always `file`.

190

191 - `:file`

192

193 - `purpose: :assistants | :assistants_output | :batch | 5 more`

194

195 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

196

197 - `:assistants`

198

199 - `:assistants_output`

200

201 - `:batch`

202

203 - `:batch_output`

204

205 - `:"fine-tune"`

206

207 - `:"fine-tune-results"`

208

209 - `:vision`

210

211 - `:user_data`

212

213 - `status: :uploaded | :processed | :error`

214

215 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

216

217 - `:uploaded`

218

219 - `:processed`

220

221 - `:error`

222

223 - `expires_at: Integer`

224

225 The Unix timestamp (in seconds) for when the file will expire.

226

227 - `status_details: String`

228

229 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

230

231### Example

232

233```ruby

234require "openai"

235

236openai = OpenAI::Client.new(api_key: "My API Key")

237

238file_object = openai.files.create(file: StringIO.new("Example data"), purpose: {})

239

240puts(file_object)

241```

242

243#### Response

244

245```json

246{

247 "id": "id",

248 "bytes": 0,

249 "created_at": 0,

250 "filename": "filename",

251 "object": "file",

252 "purpose": "assistants",

253 "status": "uploaded",

254 "expires_at": 0,

255 "status_details": "status_details"

256}

257```

258

259## Delete file

260

261`files.delete(file_id) -> FileDeleted`

262

263**delete** `/files/{file_id}`

264

265Delete file

266

267### Parameters

268

269- `file_id: String`

270

271### Returns

272

273- `class FileDeleted`

274

275 - `id: String`

276

277 - `deleted: bool`

278

279 - `object: :file`

280

281 - `:file`

282

283### Example

284

285```ruby

286require "openai"

287

288openai = OpenAI::Client.new(api_key: "My API Key")

289

290file_deleted = openai.files.delete("file_id")

291

292puts(file_deleted)

293```

294

295#### Response

296

297```json

298{

299 "id": "id",

300 "deleted": true,

301 "object": "file"

302}

303```

304

305## Retrieve file

306

307`files.retrieve(file_id) -> FileObject`

308

309**get** `/files/{file_id}`

310

311Retrieve file

312

313### Parameters

314

315- `file_id: String`

316

317### Returns

318

319- `class FileObject`

320

321 The `File` object represents a document that has been uploaded to OpenAI.

322

323 - `id: String`

324

325 The file identifier, which can be referenced in the API endpoints.

326

327 - `bytes: Integer`

328

329 The size of the file, in bytes.

330

331 - `created_at: Integer`

332

333 The Unix timestamp (in seconds) for when the file was created.

334

335 - `filename: String`

336

337 The name of the file.

338

339 - `object: :file`

340

341 The object type, which is always `file`.

342

343 - `:file`

344

345 - `purpose: :assistants | :assistants_output | :batch | 5 more`

346

347 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

348

349 - `:assistants`

350

351 - `:assistants_output`

352

353 - `:batch`

354

355 - `:batch_output`

356

357 - `:"fine-tune"`

358

359 - `:"fine-tune-results"`

360

361 - `:vision`

362

363 - `:user_data`

364

365 - `status: :uploaded | :processed | :error`

366

367 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

368

369 - `:uploaded`

370

371 - `:processed`

372

373 - `:error`

374

375 - `expires_at: Integer`

376

377 The Unix timestamp (in seconds) for when the file will expire.

378

379 - `status_details: String`

380

381 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

382

383### Example

384

385```ruby

386require "openai"

387

388openai = OpenAI::Client.new(api_key: "My API Key")

389

390file_object = openai.files.retrieve("file_id")

391

392puts(file_object)

393```

394

395#### Response

396

397```json

398{

399 "id": "id",

400 "bytes": 0,

401 "created_at": 0,

402 "filename": "filename",

403 "object": "file",

404 "purpose": "assistants",

405 "status": "uploaded",

406 "expires_at": 0,

407 "status_details": "status_details"

408}

409```

410

411## Retrieve file content

412

413`files.content(file_id) -> StringIO`

414

415**get** `/files/{file_id}/content`

416

417Retrieve file content

418

419### Parameters

420

421- `file_id: String`

422

423### Returns

424

425- `StringIO`

426

427### Example

428

429```ruby

430require "openai"

431

432openai = OpenAI::Client.new(api_key: "My API Key")

433

434response = openai.files.content("file_id")

435

436puts(response)

437```

438

439## Domain Types

440

441### File Content

442

443- `FileContent = String`

444

445### File Deleted

446

447- `class FileDeleted`

448

449 - `id: String`

450

451 - `deleted: bool`

452

453 - `object: :file`

454

455 - `:file`

456

457### File Object

458

459- `class FileObject`

460

461 The `File` object represents a document that has been uploaded to OpenAI.

462

463 - `id: String`

464

465 The file identifier, which can be referenced in the API endpoints.

466

467 - `bytes: Integer`

468

469 The size of the file, in bytes.

470

471 - `created_at: Integer`

472

473 The Unix timestamp (in seconds) for when the file was created.

474

475 - `filename: String`

476

477 The name of the file.

478

479 - `object: :file`

480

481 The object type, which is always `file`.

482

483 - `:file`

484

485 - `purpose: :assistants | :assistants_output | :batch | 5 more`

486

487 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

488

489 - `:assistants`

490

491 - `:assistants_output`

492

493 - `:batch`

494

495 - `:batch_output`

496

497 - `:"fine-tune"`

498

499 - `:"fine-tune-results"`

500

501 - `:vision`

502

503 - `:user_data`

504

505 - `status: :uploaded | :processed | :error`

506

507 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

508

509 - `:uploaded`

510

511 - `:processed`

512

513 - `:error`

514

515 - `expires_at: Integer`

516

517 The Unix timestamp (in seconds) for when the file will expire.

518

519 - `status_details: String`

520

521 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

522

523### File Purpose

524

525- `FilePurpose = untyped`

ruby/resources/files/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 UTC

Files

List files

Parameters

Returns

Example

Response

Upload file

Parameters

Returns

Example

Response

Delete file

Parameters

Returns

Example

Response

Retrieve file

Parameters

Returns

Example

Response

Retrieve file content

Parameters

Returns

Example

Domain Types

File Content

File Deleted

File Object

File Purpose