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	Example	Description
OpenAI API Key	string	Yes	sk-...	Your OpenAI API key for this Module. Stored securely. Find it in OpenAI Console → API keys → Create new secret key.
OpenAI Organization	string	No	org-abc123	Your OpenAI organization ID, 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 the OpenAI 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; the API key is configured there.
• OpenAI Files & Vector Stores — upload JSONL inputs and download batch outputs.