API reference · Schema
File
idstringrequiredUnique ID (`file_…`)
ID with prefix file_
objectstringrequiredAlways `file`: the type of this object
One of
filebytesintegerrequiredSize in bytes
created_atintegerrequiredUnix seconds (OpenAI shape)
filenamestringrequiredThe file name given at upload
purposestringrequired`fine-tune`, `batch` or `evaluation` for uploads; `batch_output` and `evaluation_results` for files the platform writes
statusstringrequiredOpenAI-shaped status: processed = valid, error = invalid
One of
uploadedprocessederrorstatus_detailsstring | nullrequiredFor an invalid file, the first error and how many more there are; null otherwise
expires_atinteger | nullrequiredWhen it expires (null: never) (ISO 8601, UTC)
project_idstringrequiredProject it belongs to
ID with prefix prj_
uploaded_atstring (date-time)requiredTime uploaded (ISO 8601, UTC)
sha256string | nullrequiredSHA-256 of the content, hex
content_typestring | nullrequiredMedia type of the uploaded `file` part; null when the upload gave none
validationobjectrequiredWhether the content is usable for its purpose, and why not
ShowHide 2 fields of
validationstatestringrequiredpending → running → valid | invalid
One of
pendingrunningvalidinvalidreportFileValidationReport | any JSON | nullrequiredWhat validation found; null until validation has finished
ShowHide 15 fields of
reportvalidbooleanrequiredTrue when the file has no errors and can be used for its purpose
formatstring | nullrequiredDetected format (every example shares one; `dataset` for evaluation data)
One of
chatprompt_completiontextpreferencebatch_requestsdatasetexamplesintegerrequiredLines holding an example, request or dataset row (blank lines are not counted)
linesintegerrequiredLines read, including blank lines
bytesintegerrequiredSize in bytes
token_estimateintegerrequiredEstimated tokens over all examples (characters / 4, plus template overhead)
max_example_token_estimateintegerrequiredEstimated tokens of the largest single example, to compare with a model's maximum sequence length
token_estimate_methodstringrequiredHow token counts were estimated: characters divided by 4, rounded up
One of
characters_div_4error_countintegerrequiredErrors found in the file, including those not listed in `errors`
errorsarray of objectrequiredThe first 100 errors, with 1-based line numbers
ShowHide 3 fields of
errorslineintegerrequired1-based line number in the file
codestringrequiredMachine-readable code
messagestringrequiredOne sentence for people
warningsarray of stringrequiredProblems that do not make the file invalid, such as very few training examples
truncatedbooleanrequiredValidation stopped early (too many errors)
validated_atstring (date-time)requiredTime validated (ISO 8601, UTC)
datasetobjectEvaluation datasets (purpose `evaluation`): rows and columns
ShowHide 6 fields of
datasetformatstringrequiredJSON Lines or CSV with a header row
One of
jsonlcsvrowsintegerrequiredData rows (a CSV header is not counted)
columnsarray of stringrequiredIn order of first appearance
column_rowsobjectrequiredRows that have each column
column_bytesobjectrequiredUTF-8 bytes of each column's values over all rows
max_row_bytesintegerrequiredUTF-8 bytes of the largest row
requestsobject | nullrequiredBatch files: the models and URLs the valid lines name, with how many lines name each, most used first. Null for training files (and for files validated before this existed).
ShowHide 3 fields of
requestsmodelsarray of objectrequiredModels named in the `body.model` of valid lines
urlsarray of objectrequiredRequest paths named in the `url` of valid lines
truncatedbooleanrequiredMore than 50 distinct models or URLs: only the most used are listed
{
"id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
"object": "file",
"bytes": 1,
"created_at": 1,
"filename": "string",
"purpose": "fine-tune",
"status": "uploaded",
"status_details": "string",
"expires_at": 1,
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"uploaded_at": "2026-01-01T00:00:00.000Z",
"sha256": "string",
"content_type": "string",
"validation": {
"state": "pending",
"report": {
"valid": true,
"format": "chat",
"examples": 1,
"lines": 1,
"bytes": 1,
"token_estimate": 1,
"max_example_token_estimate": 1,
"token_estimate_method": "characters_div_4",
"error_count": 1,
"errors": [
{
"line": 1,
"code": "string",
"message": "string"
}
],
"warnings": [
"string"
],
"truncated": true,
"validated_at": "2026-01-01T00:00:00.000Z",
"dataset": {
"format": "jsonl",
"rows": 1,
"columns": [
"string"
],
"column_rows": {},
"column_bytes": {},
"max_row_bytes": 1
},
"requests": {
"models": [
{
"model": null,
"lines": null
}
],
"urls": [
{
"url": null,
"lines": null
}
],
"truncated": true
}
}
}
}Used by
- List files in the project
GET /v1/files - Upload a file (multipart form: file, purpose); validated asynchronously
POST /v1/files - Get a file, with its validation state and report
GET /v1/files/{file_id}