OpenAI Batch & Fine-tuning

Bulk inference at a 50 % discount and custom fine-tuned models, driven from your workflow.

This Module submits, polls, and cancels OpenAI batch jobs (many requests processed within a 24-hour window at half price) and fine-tuning jobs (train a custom model on your own examples). Both run on JSONL files you upload first with the OpenAI Files & Vector Stores Module.

How it works

Both job types follow the same submit → poll → collect pattern:

1. Upload a JSONL file (purpose=batch or purpose=fine-tune) with OpenAIUploadFileTask.
2. Submit the job here; you get back a job ID immediately the submit Tasks do not wait.
3. Poll the job ID until its status reaches a terminal value (completed / failed / cancelled); jobs typically take hours.
4. Collect results: batch jobs produce an output file ID you can download; fine-tuning produces a new model name you can use in any chat Task.

Configuration

Each OpenAI Module is configured separately, per Environment this Module has its own API key, so you can reuse the key you set on the core OpenAI Module or use a dedicated one (for example to track this capability's spend on its own).

Field	Type	Required	Description
OpenAI API Key	string	Yes	Your OpenAI API key (sk-...) for this Module. Stored securely. Find it in OpenAI Console → API keys → Create new secret key.
OpenAI Organization	string	No	Your OpenAI organization ID (e.g. org-abc123), if your account belongs to one.

Tasks

All Tasks in this Module are Generic (all Channels) they run the same regardless of how the Session was started.

Output fields: type a variable name without braces (for example batchId) and pick its type (string, number, true/false, object, date). The Task saves its result there, and any later Task can use it by writing {batchId}.

OpenAIBatchSubmitTask

Submits a batch job over an uploaded JSONL request file. Does not wait batches typically take hours. Poll the batch ID with OpenAIGetBatchTask, via the OpenAI dashboard, or from a separate workflow.

Property	Type	Required	Example	Description
Input File ID	string	Yes	{batchInputFileId}	ID of an uploaded JSONL file (purpose=batch). Supports {variable} placeholders.
Endpoint	string	Yes	/v1/chat/completions	/v1/chat/completions, /v1/embeddings, /v1/completions, or /v1/responses.
Completion Window	string	No	24h	Currently 24h is the only supported value.
Output Variable	string	Yes	batchId	Variable name (no braces). Receives the batch ID (batch_…).

Example: Set Input File ID = {batchInputFileId}, Endpoint = /v1/chat/completions, Output Variable = batchId. The Task submits the job and immediately saves the new ID (e.g. batch_abc123) to batchId the batch keeps processing on OpenAI's side.

OpenAIGetBatchTask

Polls a batch job by ID. Use this in a loop until the status reaches a terminal value (completed / failed / cancelled).

Property	Type	Required	Example	Description
Batch ID	string	Yes	{batchId}	batch_… ID. Supports {variable} placeholders.
Output Variable	object	Yes	batchInfo	Variable name (no braces). Receives an entry with status, output_file_id, error_file_id, request_counts.

Example: Set Batch ID = {batchId}, Output Variable = batchInfo. While processing, batchInfo.status is in_progress; once done, it is completed and batchInfo.output_file_id holds the result file to download.

OpenAICancelBatchTask

Cancels an in-progress batch.

Property	Type	Required	Example	Description
Batch ID	string	Yes	{batchId}	batch_… ID. Supports {variable} placeholders.

Example: Set Batch ID = {batchId} on a cleanup branch already-completed requests are kept, the rest are cancelled.

OpenAISubmitFineTuningTask

Submits a fine-tuning job over an uploaded JSONL training file. Does not wait fine-tuning takes hours; poll with OpenAIGetFineTuningJobTask.

Property	Type	Required	Example	Description
Base Model	string	Yes	gpt-4o-mini-2024-07-18	Base model to fine-tune.
Training File ID	string	Yes	{trainingFileId}	ID of an uploaded JSONL file (purpose=fine-tune). Supports {variable} placeholders.
Validation File ID	string	No	{validationFileId}	Optional. ID of a validation JSONL file.
Suffix	string	No	custom-2026-04	Optional. Custom suffix appended to the resulting fine-tuned model name.
Output Variable	string	Yes	jobId	Variable name (no braces). Receives the fine-tuning job ID.

Example: Set Base Model = gpt-4o-mini-2024-07-18, Training File ID = {trainingFileId}, Suffix = support-bot, Output Variable = jobId. The Task saves the job ID to jobId; hours later the finished model is named like ft:gpt-4o-mini-2024-07-18:org:support-bot:xyz.

OpenAIGetFineTuningJobTask

Polls a fine-tuning job. Saves its current status and the final fine_tuned_model name when completed.

Property	Type	Required	Example	Description
Job ID	string	Yes	{fineTuningJobId}	Fine-tuning job ID. Supports {variable} placeholders.
Output Variable	object	Yes	jobInfo	Variable name (no braces). Receives the job status entry (includes fine_tuned_model once done).

Example: Set Job ID = {jobId}, Output Variable = jobInfo. Once jobInfo.status is succeeded, jobInfo.fine_tuned_model holds the model name to use in any chat Task.

OpenAICancelFineTuningTask

Cancels an in-progress fine-tuning job.

Property	Type	Required	Example	Description
Job ID	string	Yes	{fineTuningJobId}	Fine-tuning job ID. Supports {variable} placeholders.

Example: Set Job ID = {jobId} to abort a training run started with the wrong file before it consumes the full training cost.

Common recipes

Submit a batch and collect the results on a schedule

Submit the batch from one Process; a second, scheduled Process polls the ID and downloads the output when done. Upload/download Tasks come from the OpenAI Files & Vector Stores Module; LogTask comes from the Standard Module.

1. OpenAIUploadFileTask Source = {jsonlUrl}, File Name = requests.jsonl, Purpose = batch, Output Variable = batchInputFileId.
2. OpenAIBatchSubmitTask Input File ID = {batchInputFileId}, Endpoint = /v1/chat/completions, Output Variable = batchId. Store {batchId} where the polling Process can read it.
3. In the scheduled Process: OpenAIGetBatchTask Batch ID = {batchId}, Output Variable = batchInfo. Route on {batchInfo.status} with a gateway labeled completed / other.
4. completed branch: OpenAIDownloadFileTask File ID = {batchInfo.output_file_id}, MIME Type = application/json, Output Variable = results.
5. other branch: LogTask log "batch still running" and end; the next scheduled run polls again.

Best practices

1. Don't poll in a tight loop batch and fine-tuning jobs take hours; poll from a scheduled workflow rather than spinning inside one Session.
2. Use the fine-tuned model like any other once fine_tuned_model appears in the job status, pass that name as the Model of a chat Task in the core OpenAI Module.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required property is missing or an output field is not a valid variable name details
4001	ModuleException	OpenAI rejected the job submission, poll, or cancellation details
4008	ModuleMissingConfiguration	The OpenAI API key is not set in this Module's Environment configuration details
4009	ModuleInputEmpty	A required input (such as a file or job ID) resolved to an empty value details
4012	ModuleInvalidData	The Session data could not be read or the job response could not be processed details

See the Error Code Reference for the full list.

Related pages

• OpenAI Module the family core chat, embeddings, and moderation Tasks.
• OpenAI Files & Vector Stores upload JSONL inputs and download batch outputs.