SpyBara
Go Premium

cli/resources/files/index.md 2026-05-05 23:00 UTC to 2026-05-07 21:57 UTC

547 added, 0 removed.

2026
Wed 27 06:42 Fri 22 06:33 Wed 20 06:35 Tue 19 06:34 Mon 18 22:01 Mon 11 18:00 Thu 7 21:57 Tue 5 23:00 Sat 2 05:57

Files

List files

$ openai files list

get /files

Returns a list of files.

Parameters

  • --after: optional 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: optional number

    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: optional "asc" or "desc"

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

  • --purpose: optional string

    Only return files with the given purpose.

Returns

  • ListFilesResponse: object { data, first_id, has_more, 2 more }

    • data: array of FileObject

      • id: string

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

      • bytes: number

        The size of the file, in bytes.

      • created_at: number

        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.

      • purpose: "assistants" or "assistants_output" or "batch" or 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" or "processed" or "error"

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

        • "uploaded"

        • "processed"

        • "error"

      • expires_at: optional number

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

      • status_details: optional string

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

    • first_id: string

    • has_more: boolean

    • last_id: string

    • object: string

Example

openai files list \
  --api-key 'My API Key'

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

$ openai files create

post /files

Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and each project can store up to 2.5 TB of files in total. There is no organization-wide storage limit. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user.

  • The Assistants API supports files up to 2 million tokens and of specific file types. See the Assistants Tools guide for details.
  • The Fine-tuning API only supports .jsonl files. The input also has certain required formats for fine-tuning chat or completions models.
  • The Batch API only supports .jsonl files up to 200 MB in size. The input also has a specific required format.
  • For Retrieval or file_search ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use /vector_stores/{vector_store_id}/file_batches instead of attaching them one by one. Vector store attachment has separate limits from file upload, including 2,000 attached files per minute per organization.

Please contact us if you need to increase these storage limits.

Parameters

  • --file: string

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

  • --purpose: "assistants" or "batch" or "fine-tune" or 3 more

    The intended purpose of the uploaded file. One of:

    • assistants: Used in the Assistants API
    • batch: Used in the Batch API
    • fine-tune: Used for fine-tuning
    • vision: Images used for vision fine-tuning
    • user_data: Flexible file type for any purpose
    • evals: Used for eval data sets

  • --expires-after: optional object { 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.

Returns

  • file_object: object { id, bytes, created_at, 6 more }

    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: number

      The size of the file, in bytes.

    • created_at: number

      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.

    • purpose: "assistants" or "assistants_output" or "batch" or 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" or "processed" or "error"

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

      • "uploaded"

      • "processed"

      • "error"

    • expires_at: optional number

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

    • status_details: optional string

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

Example

openai files create \
  --api-key 'My API Key' \
  --file 'Example data' \
  --purpose assistants

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

$ openai files delete

delete /files/{file_id}

Delete a file and remove it from all vector stores.

Parameters

  • --file-id: string

    The ID of the file to use for this request.

Returns

  • file_deleted: object { id, deleted, object }

    • id: string

    • deleted: boolean

    • object: "file"

Example

openai files delete \
  --api-key 'My API Key' \
  --file-id file_id

Response

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

Retrieve file

$ openai files retrieve

get /files/{file_id}

Returns information about a specific file.

Parameters

  • --file-id: string

    The ID of the file to use for this request.

Returns

  • file_object: object { id, bytes, created_at, 6 more }

    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: number

      The size of the file, in bytes.

    • created_at: number

      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.

    • purpose: "assistants" or "assistants_output" or "batch" or 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" or "processed" or "error"

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

      • "uploaded"

      • "processed"

      • "error"

    • expires_at: optional number

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

    • status_details: optional string

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

Example

openai files retrieve \
  --api-key 'My API Key' \
  --file-id file_id

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

$ openai files content

get /files/{file_id}/content

Returns the contents of the specified file.

Parameters

  • --file-id: string

    The ID of the file to use for this request.

Returns

  • unnamed_schema_0: file path

Example

openai files content \
  --api-key 'My API Key' \
  --file-id file_id

Domain Types

File Content

  • file_content: string

File Deleted

  • file_deleted: object { id, deleted, object }

    • id: string

    • deleted: boolean

    • object: "file"

File Object

  • file_object: object { id, bytes, created_at, 6 more }

    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: number

      The size of the file, in bytes.

    • created_at: number

      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.

    • purpose: "assistants" or "assistants_output" or "batch" or 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" or "processed" or "error"

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

      • "uploaded"

      • "processed"

      • "error"

    • expires_at: optional number

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

    • status_details: optional string

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

File Purpose

  • file_purpose: "assistants" or "batch" or "fine-tune" or 3 more

    The intended purpose of the uploaded file. One of:

    • assistants: Used in the Assistants API

    • batch: Used in the Batch API

    • fine-tune: Used for fine-tuning

    • vision: Images used for vision fine-tuning

    • user_data: Flexible file type for any purpose

    • evals: Used for eval data sets

    • "assistants"

    • "batch"

    • "fine-tune"

    • "vision"

    • "user_data"

    • "evals"