Skip to main content
API docs by Redocly

Intelligence Foundry API (1.0.0)

Download OpenAPI specification:Download

The Intelligence Foundry REST API. Please see https://docs.crusoecloud.com/ for more details.

Fine-tuning

Creates a fine-tuning job which begins the process of creating a new model from a given dataset. Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete. [Learn more about fine-tuning](/docs/guides/model-optimization)

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
string or string

The name of the model to fine-tune. You can select one of the supported models.

training_file
required
string

The ID of an uploaded file that contains training data.

See upload file for how to upload a file.

Your dataset must be formatted as a JSONL file. Additionally, you must upload your file with the purpose fine-tune.

The contents of the file should differ depending on if the model uses the chat, completions format, or if the fine-tuning method uses the preference format.

See the fine-tuning guide for more details.

suffix
string or null [ 1 .. 64 ] characters ^[a-zA-Z0-9][a-zA-Z0-9-]*$

A string of up to 64 characters that will be added to your fine-tuned model name.

For example, a suffix of "custom-model-name" would produce a model name like ft:gpt-4o-mini:openai:custom-model-name:7p4lURel.

validation_file
string or null

The ID of an uploaded file that contains validation data.

If you provide this file, the data is used to generate validation metrics periodically during fine-tuning. These metrics can be viewed in the fine-tuning results file. The same data should not be present in both train and validation files.

Your dataset must be formatted as a JSONL file. You must upload your file with the purpose fine-tune.

See the fine-tuning guide for more details.

seed
integer or null [ 0 .. 2147483647 ]

The seed controls the reproducibility of the job. Passing in the same seed and job parameters should produce the same results, but may differ in rare cases. If a seed is not specified, one will be generated for you.

object (FineTuneMethod)

The method used for fine-tuning. Only supervised is supported.

(object or null) or (object or null) (Metadata)

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

Responses

Request samples

Content type
application/json
{
  • "model": "gpt-4o-mini",
  • "training_file": "file-abc123",
  • "suffix": "string",
  • "validation_file": "file-abc123",
  • "seed": 42,
  • "method": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": 0,
  • "error": {
    },
  • "fine_tuned_model": "string",
  • "finished_at": 0,
  • "model": "string",
  • "object": "fine_tuning.job",
  • "organization_id": "string",
  • "result_files": [
    ],
  • "status": "validating_files",
  • "trained_tokens": 0,
  • "training_file": "string",
  • "validation_file": "string",
  • "seed": 0,
  • "estimated_finish": 0,
  • "method": {
    },
  • "metadata": {
    },
  • "job_training_config": null
}

List your organization's fine-tuning jobs

Authorizations:
ApiKeyAuth
query Parameters
model
Array of strings

Filter to jobs for these base model registry IDs.

suffix
Array of strings

Filter to jobs with these suffixes.

status
Array of strings
Items Enum: "validating_files" "queued" "running" "succeeded" "failed" "cancelled" "paused"

Filter to jobs in these statuses.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "object": "list"
}

Get info about a fine-tuning job. [Learn more about fine-tuning](/docs/guides/model-optimization)

Authorizations:
ApiKeyAuth
path Parameters
fine_tuning_job_id
required
string

The ID of the fine-tuning job.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": 0,
  • "error": {
    },
  • "fine_tuned_model": "string",
  • "finished_at": 0,
  • "model": "string",
  • "object": "fine_tuning.job",
  • "organization_id": "string",
  • "result_files": [
    ],
  • "status": "validating_files",
  • "trained_tokens": 0,
  • "training_file": "string",
  • "validation_file": "string",
  • "seed": 0,
  • "estimated_finish": 0,
  • "method": {
    },
  • "metadata": {
    },
  • "job_training_config": null
}

List checkpoints for a fine-tuning job.

Authorizations:
ApiKeyAuth
path Parameters
fine_tuning_job_id
required
string

The ID of the fine-tuning job to get checkpoints for.

query Parameters
after
string

Identifier for the last checkpoint ID from the previous pagination request.

limit
integer
Default: 10

Number of checkpoints to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "first_id": "string",
  • "last_id": "string",
  • "has_more": true
}

Immediately cancel a fine-tune job.

Authorizations:
ApiKeyAuth
path Parameters
fine_tuning_job_id
required
string

The ID of the fine-tuning job to cancel.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": 0,
  • "error": {
    },
  • "fine_tuned_model": "string",
  • "finished_at": 0,
  • "model": "string",
  • "object": "fine_tuning.job",
  • "organization_id": "string",
  • "result_files": [
    ],
  • "status": "validating_files",
  • "trained_tokens": 0,
  • "training_file": "string",
  • "validation_file": "string",
  • "seed": 0,
  • "estimated_finish": 0,
  • "method": {
    },
  • "metadata": {
    },
  • "job_training_config": null
}

Pause a fine-tune job.

Authorizations:
ApiKeyAuth
path Parameters
fine_tuning_job_id
required
string

The ID of the fine-tuning job to pause.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": 0,
  • "error": {
    },
  • "fine_tuned_model": "string",
  • "finished_at": 0,
  • "model": "string",
  • "object": "fine_tuning.job",
  • "organization_id": "string",
  • "result_files": [
    ],
  • "status": "validating_files",
  • "trained_tokens": 0,
  • "training_file": "string",
  • "validation_file": "string",
  • "seed": 0,
  • "estimated_finish": 0,
  • "method": {
    },
  • "metadata": {
    },
  • "job_training_config": null
}

Resume a fine-tune job.

Authorizations:
ApiKeyAuth
path Parameters
fine_tuning_job_id
required
string

The ID of the fine-tuning job to resume.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": 0,
  • "error": {
    },
  • "fine_tuned_model": "string",
  • "finished_at": 0,
  • "model": "string",
  • "object": "fine_tuning.job",
  • "organization_id": "string",
  • "result_files": [
    ],
  • "status": "validating_files",
  • "trained_tokens": 0,
  • "training_file": "string",
  • "validation_file": "string",
  • "seed": 0,
  • "estimated_finish": 0,
  • "method": {
    },
  • "metadata": {
    },
  • "job_training_config": null
}

Get status updates for a fine-tuning job.

Authorizations:
ApiKeyAuth
path Parameters
fine_tuning_job_id
required
string

The ID of the fine-tuning job to get events for.

query Parameters
after
string

Identifier for the last event from the previous pagination request.

limit
integer
Default: 20

Number of events to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "has_more": true
}

Get fine-tuning job metrics

Get time-series training metrics for a fine-tuning job.

Authorizations:
ApiKeyAuth
path Parameters
fine_tuning_job_id
required
string

The ID of the fine-tuning job to get metrics for.

query Parameters
metric_names
Array of strings
Items Enum: "ev_loss" "ev_eval_loss" "ev_current_step" "ev_total_steps" "ev_learning_rate" "ev_grad_norm" "ev_num_input_tokens_seen" "ev_eval_samples_per_second" "ev_eval_steps_per_second" "ev_estimated_finish" "ev_train_loss" "ev_train_runtime" "ev_train_samples_per_second" "ev_train_steps_per_second" "ev_train_tokens_per_second" "ev_total_flos"

Filter to specific metric names.

cursor
string

Epoch timestamp cursor for pagination.

step
string

Step duration for aggregation (e.g. 1m, 30s).

x_axis
string
Enum: "timestamp" "step_count"

X-axis type for returned data points (default timestamp).

Responses

Response samples

Content type
application/json
{
  • "object": "fine_tuning.job.metrics",
  • "fine_tuning_job_id": "string",
  • "x_axis": "timestamp",
  • "metrics": [
    ]
}

Files

Returns a list of files.

Authorizations:
ApiKeyAuth
query Parameters
purpose
string

Only return files with the given purpose.

limit
integer
Default: 10000

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
string
Default: "desc"
Enum: "asc" "desc"

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

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.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "first_id": "file-abc123",
  • "last_id": "file-abc456",
  • "has_more": false
}

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](/docs/assistants/tools) for details. - The Fine-tuning API only supports `.jsonl` files. The input also has certain required formats for fine-tuning [chat](/docs/api-reference/fine-tuning/chat-input) or [completions](/docs/api-reference/fine-tuning/completions-input) models. - The Batch API only supports `.jsonl` files up to 200 MB in size. The input also has a specific required [format](/docs/api-reference/batch/request-input). - 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`](/docs/api-reference/vector-stores-file-batches/createBatch) 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](https://help.openai.com/) if you need to increase these storage limits.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

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

purpose
required
string
Enum: "assistants" "batch" "fine-tune" "vision" "user_data" "evals"

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
object (File expiration policy)

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.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "bytes": 0,
  • "created_at": 0,
  • "expires_at": 0,
  • "filename": "string",
  • "object": "file",
  • "purpose": "assistants",
  • "status": "uploaded",
  • "status_details": "string",
  • "is_cmek_encrypted": false
}

Returns information about a specific file.

Authorizations:
ApiKeyAuth
path Parameters
file_id
required
string

The ID of the file to use for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "bytes": 0,
  • "created_at": 0,
  • "expires_at": 0,
  • "filename": "string",
  • "object": "file",
  • "purpose": "assistants",
  • "status": "uploaded",
  • "status_details": "string",
  • "is_cmek_encrypted": false
}

Delete a file and remove it from all vector stores.

Authorizations:
ApiKeyAuth
path Parameters
file_id
required
string

The ID of the file to use for this request.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "file",
  • "deleted": true
}

Returns the contents of the specified file.

Authorizations:
ApiKeyAuth
path Parameters
file_id
required
string

The ID of the file to use for this request.

Responses

Response samples

Content type
application/json
"string"

Batch

List your organization's batches.

Authorizations:
ApiKeyAuth
query 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
Default: 20

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

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "first_id": "batch_abc123",
  • "last_id": "batch_abc456",
  • "has_more": true,
  • "object": "list"
}

Creates and executes a batch from an uploaded file of requests

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
input_file_id
required
string

The ID of an uploaded file that contains requests for the new batch. The file must be a JSONL file uploaded with the purpose batch, with at most 10,000 requests, up to 1 GB in size. Each line must omit the model field — the batch-level model applies to every request.

endpoint
required
string
Value: "/v1/chat/completions"

The endpoint to be used for all requests in the batch. Currently only /v1/chat/completions is supported.

completion_window
required
string
Value: "24h"

The time frame within which the batch should be processed. Currently only 24h is supported.

(object or null) or (object or null) (Metadata)

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

model
required
string

The model to run every request in the batch against. The model must be batch-available. Per-line request bodies must not contain a model field.

Responses

Request samples

Content type
application/json
{
  • "input_file_id": "string",
  • "endpoint": "/v1/chat/completions",
  • "completion_window": "24h",
  • "metadata": {
    },
  • "model": "model-qwen-qwen3-0-6b-e78b5b5f"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "batch",
  • "endpoint": "string",
  • "model": "string",
  • "errors": {
    },
  • "input_file_id": "string",
  • "completion_window": "string",
  • "status": "validating",
  • "output_file_id": "string",
  • "error_file_id": "string",
  • "created_at": 0,
  • "in_progress_at": 0,
  • "expires_at": 0,
  • "finalizing_at": 0,
  • "completed_at": 0,
  • "failed_at": 0,
  • "expired_at": 0,
  • "cancelling_at": 0,
  • "cancelled_at": 0,
  • "request_counts": {
    },
  • "usage": {
    },
  • "metadata": {
    }
}

Retrieves a batch.

Authorizations:
ApiKeyAuth
path Parameters
batch_id
required
string

The ID of the batch to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "batch",
  • "endpoint": "string",
  • "model": "string",
  • "errors": {
    },
  • "input_file_id": "string",
  • "completion_window": "string",
  • "status": "validating",
  • "output_file_id": "string",
  • "error_file_id": "string",
  • "created_at": 0,
  • "in_progress_at": 0,
  • "expires_at": 0,
  • "finalizing_at": 0,
  • "completed_at": 0,
  • "failed_at": 0,
  • "expired_at": 0,
  • "cancelling_at": 0,
  • "cancelled_at": 0,
  • "request_counts": {
    },
  • "usage": {
    },
  • "metadata": {
    }
}

Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file.

Authorizations:
ApiKeyAuth
path Parameters
batch_id
required
string

The ID of the batch to cancel.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "batch",
  • "endpoint": "string",
  • "model": "string",
  • "errors": {
    },
  • "input_file_id": "string",
  • "completion_window": "string",
  • "status": "validating",
  • "output_file_id": "string",
  • "error_file_id": "string",
  • "created_at": 0,
  • "in_progress_at": 0,
  • "expires_at": 0,
  • "finalizing_at": 0,
  • "completed_at": 0,
  • "failed_at": 0,
  • "expired_at": 0,
  • "cancelling_at": 0,
  • "cancelled_at": 0,
  • "request_counts": {
    },
  • "usage": {
    },
  • "metadata": {
    }
}

Models

List available models

Lists the currently available models, and provides basic information about each one such as the owner and availability. All models the project can access are returned.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ]
}

Retrieve a model

Retrieves a model instance, providing basic information about the model such as the owner and availability.

Authorizations:
ApiKeyAuth
path Parameters
model
required
string

The encoded ID of the model (returned in the id field from list)

Responses

Response samples

Content type
application/json
{
  • "id": "admin-model-abc123",
  • "object": "model",
  • "owned_by": "org-123",
  • "model_source": "huggingface",
  • "model_name": "meta-llama/Llama-2-7b-hf",
  • "model_revision": "main",
  • "globally_available": false,
  • "project_ids": [
    ],
  • "inference_available": true,
  • "fine_tuning_available": false,
  • "batch_available": false,
  • "model_type": "base_model",
  • "base_model_id": "model-abc123",
  • "created": 1700000000
}

Delete a fine-tuned model

Delete a fine-tuned model owned by the caller's project. Refuses deletion of globally available models, models not solely owned by the caller's project, or models referenced by any non-terminal fine-tuning job in the project.

Authorizations:
ApiKeyAuth
path Parameters
model
required
string

The encoded ID of the model (returned in the id field from list)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "model",
  • "deleted": true
}

Download an adapter model

Download an adapter model as a zip archive containing adapter_model.safetensors and adapter_config.json. Requires ProjectReader permission.

Authorizations:
ApiKeyAuth
path Parameters
model
required
string

The ID of the adapter model to download

Responses

Public

List available models (public)

Lists the currently available models without requiring authentication. All available models are returned.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ]
}