Batches

Cancel batch

post /batches/{batch_id}/cancel

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.

Path Parameters

batch_id: string

Returns

Batch object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
  - "batch"
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional 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: optional string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: optional string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Example

curl https://api.openai.com/v1/batches/$BATCH_ID/cancel \
    -X POST \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

Example

curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

Response

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1711475133,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 23,
    "failed": 1
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

Create batch

post /batches

Creates and executes a batch from an uploaded file of requests

Body Parameters

completion_window: "24h"

The time frame within which the batch should be processed. Currently only 24h is supported.
- "24h"
endpoint: "/v1/responses" or "/v1/chat/completions" or "/v1/embeddings" or 5 more

The endpoint to be used for all requests in the batch. Currently /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations, /v1/images/generations, /v1/images/edits, and /v1/videos are supported. Note that /v1/embeddings batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
- "/v1/responses"
- "/v1/chat/completions"
- "/v1/embeddings"
- "/v1/completions"
- "/v1/moderations"
- "/v1/images/generations"
- "/v1/images/edits"
- "/v1/videos"
input_file_id: string

The ID of an uploaded file that contains requests for the new batch.

See upload file for how to upload a file.

Your input file must be formatted as a JSONL file, and must be uploaded with the purpose batch. The file can contain up to 50,000 requests, and can be up to 200 MB in size.
metadata: optional 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.
output_expires_after: optional object { anchor, seconds }

The expiration policy for the output and/or error file that are generated for a batch.
- anchor: "created_at"
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: created_at. Note that the anchor is the file creation time, not the time the batch is created.
  - "created_at"
- seconds: number
  
  The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

Batch object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
  - "batch"
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional 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: optional string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: optional string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Example

curl https://api.openai.com/v1/batches \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "completion_window": "24h",
          "endpoint": "/v1/responses",
          "input_file_id": "input_file_id"
        }'

Response

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

Example

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

Response

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

List batches

get /batches

List your organization's batches.

Query 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 100, and the default is 20.

Returns

data: array of Batch
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
  - "batch"
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional 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: optional string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: optional string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.
has_more: boolean
object: "list"
- "list"
first_id: optional string
last_id: optional string

Example

curl https://api.openai.com/v1/batches \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "data": [
    {
      "id": "id",
      "completion_window": "completion_window",
      "created_at": 0,
      "endpoint": "endpoint",
      "input_file_id": "input_file_id",
      "object": "batch",
      "status": "validating",
      "cancelled_at": 0,
      "cancelling_at": 0,
      "completed_at": 0,
      "error_file_id": "error_file_id",
      "errors": {
        "data": [
          {
            "code": "code",
            "line": 0,
            "message": "message",
            "param": "param"
          }
        ],
        "object": "object"
      },
      "expired_at": 0,
      "expires_at": 0,
      "failed_at": 0,
      "finalizing_at": 0,
      "in_progress_at": 0,
      "metadata": {
        "foo": "string"
      },
      "model": "model",
      "output_file_id": "output_file_id",
      "request_counts": {
        "completed": 0,
        "failed": 0,
        "total": 0
      },
      "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 0
      }
    }
  ],
  "has_more": true,
  "object": "list",
  "first_id": "batch_abc123",
  "last_id": "batch_abc456"
}

Example

curl https://api.openai.com/v1/batches?limit=2 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-abc123",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-cvaTdG",
      "error_file_id": "file-HOWS94",
      "created_at": 1711471533,
      "in_progress_at": 1711471538,
      "expires_at": 1711557933,
      "finalizing_at": 1711493133,
      "completed_at": 1711493163,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {
        "customer_id": "user_123456789",
        "batch_description": "Nightly job",
      }
    },
    { ... },
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc456",
  "has_more": true
}

Retrieve batch

get /batches/{batch_id}

Retrieves a batch.

Path Parameters

batch_id: string

Returns

Batch object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
  - "batch"
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional 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: optional string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: optional string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Example

curl https://api.openai.com/v1/batches/$BATCH_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

Example

curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \

Response

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-cvaTdG",
  "error_file_id": "file-HOWS94",
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": 1711493133,
  "completed_at": 1711493163,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

Domain Types

Batch

Batch object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
  - "batch"
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional 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: optional string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: optional string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Batch Error

BatchError object { code, line, message, param }
- code: optional string
  
  An error code identifying the error type.
- line: optional number
  
  The line number of the input file where the error occurred, if applicable.
- message: optional string
  
  A human-readable message providing more details about the error.
- param: optional string
  
  The name of the parameter that caused the error, if applicable.

Batch Request Counts

BatchRequestCounts object { completed, failed, total }

The request counts for different statuses within the batch.
- completed: number
  
  Number of requests that have been completed successfully.
- failed: number
  
  Number of requests that have failed.
- total: number
  
  Total number of requests in the batch.

Batch Usage

BatchUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
- input_tokens: number
  
  The number of input tokens.
- input_tokens_details: object { cached_tokens }
  
  A detailed breakdown of the input tokens.
  - cached_tokens: number
    
    The number of tokens that were retrieved from the cache. More on prompt caching.
- output_tokens: number
  
  The number of output tokens.
- output_tokens_details: object { reasoning_tokens }
  
  A detailed breakdown of the output tokens.
  - reasoning_tokens: number
    
    The number of reasoning tokens.
- total_tokens: number
  
  The total number of tokens used.

resources/batches/index.md +164 −164

1# Batches1# Batches

2 2

~~3## Create batch~~3## Cancel batch

~~5**post** `/batches`~~

~~7Creates and executes a batch from an uploaded file of requests~~

~~9### Body Parameters~~

~~11- `completion_window: "24h"`~~

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

~~15 - `"24h"`~~

~~17- `endpoint: "/v1/responses" or "/v1/chat/completions" or "/v1/embeddings" or 5 more`~~

19 The endpoint to be used for all requests in the batch. Currently `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/completions`, `/v1/moderations`, `/v1/images/generations`, `/v1/images/edits`, and `/v1/videos` are supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.

~~21 - `"/v1/responses"`~~

~~23 - `"/v1/chat/completions"`~~

~~25 - `"/v1/embeddings"`~~

~~27 - `"/v1/completions"`~~

~~29 - `"/v1/moderations"`~~

~~31 - `"/v1/images/generations"`~~

~~33 - `"/v1/images/edits"`~~

~~35 - `"/v1/videos"`~~

~~37- `input_file_id: string`~~

~~39 The ID of an uploaded file that contains requests for the new batch.~~

~~41 See [upload file](/docs/api-reference/files/create) for how to upload a file.~~

43 Your input file must be formatted as a [JSONL file](/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 200 MB in size.

~~45- `metadata: optional Metadata`~~

~~47 Set of 16 key-value pairs that can be attached to an object. This can be~~

~~48 useful for storing additional information about the object in a structured~~

~~49 format, and querying for objects via API or the dashboard.~~

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

~~52 with a maximum length of 512 characters.~~

~~54- `output_expires_after: optional object { anchor, seconds }`~~

~~56 The expiration policy for the output and/or error file that are generated for a batch.~~

~~58 - `anchor: "created_at"`~~

59 4

~~60 Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`. Note that the anchor is the file creation time, not the time the batch is created.~~5**post** `/batches/{batch_id}/cancel`

61 6

~~62 - `"created_at"`~~7Cancels 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.

63 8

~~64 - `seconds: number`~~9### Path Parameters

65 10

~~66 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).~~11- `batch_id: string`

67 12

68### Returns13### Returns

69 14

247### Example192### Example

248 193

249```http194```http

250curl https://api.openai.com/v1/batches \195curl https://api.openai.com/v1/batches/$BATCH_ID/cancel \

251 -H 'Content-Type: application/json' \196 -X POST \

252 -H "Authorization: Bearer $OPENAI_API_KEY" \197 -H "Authorization: Bearer $OPENAI_API_KEY"

253 -d '{

254 "completion_window": "24h",

255 "endpoint": "/v1/responses",

256 "input_file_id": "input_file_id"

257 }'

258```198```

259 199

260#### Response200#### Response

315### Example255### Example

316 256

317```http257```http

318curl https://api.openai.com/v1/batches \258curl https://api.openai.com/v1/batches/batch_abc123/cancel \

319 -H "Authorization: Bearer $OPENAI_API_KEY" \259 -H "Authorization: Bearer $OPENAI_API_KEY" \

320 -H "Content-Type: application/json" \260 -H "Content-Type: application/json" \

321 -d '{261 -X POST

322 "input_file_id": "file-abc123",

323 "endpoint": "/v1/chat/completions",

324 "completion_window": "24h"

325 }'

326```262```

327 263

328#### Response264#### Response

335 "errors": null,271 "errors": null,

336 "input_file_id": "file-abc123",272 "input_file_id": "file-abc123",

337 "completion_window": "24h",273 "completion_window": "24h",

338 "status": "validating",274 "status": "cancelling",

339 "output_file_id": null,275 "output_file_id": null,

340 "error_file_id": null,276 "error_file_id": null,

341 "created_at": 1711471533,277 "created_at": 1711471533,

342 "in_progress_at": null,278 "in_progress_at": 1711471538,

343 "expires_at": null,279 "expires_at": 1711557933,

344 "finalizing_at": null,280 "finalizing_at": null,

345 "completed_at": null,281 "completed_at": null,

346 "failed_at": null,282 "failed_at": null,

347 "expired_at": null,283 "expired_at": null,

348 "cancelling_at": null,284 "cancelling_at": 1711475133,

349 "cancelled_at": null,285 "cancelled_at": null,

350 "request_counts": {286 "request_counts": {

351 "total": 0,287 "total": 100,

352 "completed": 0,288 "completed": 23,

353 "failed": 0289 "failed": 1

354 },290 },

355 "metadata": {291 "metadata": {

356 "customer_id": "user_123456789",292 "customer_id": "user_123456789",

359}295}

360```296```

361 297

362## Retrieve batch298## Create batch

363 299

364**get** `/batches/{batch_id}`300**post** `/batches`

365 301

366Retrieves a batch.302Creates and executes a batch from an uploaded file of requests

367 303

368### Path Parameters304### Body Parameters

369 305

370- `batch_id: string`306- `completion_window: "24h"`

307

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

309

310 - `"24h"`

311

312- `endpoint: "/v1/responses" or "/v1/chat/completions" or "/v1/embeddings" or 5 more`

313

314 The endpoint to be used for all requests in the batch. Currently `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/completions`, `/v1/moderations`, `/v1/images/generations`, `/v1/images/edits`, and `/v1/videos` are supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.

315

316 - `"/v1/responses"`

317

318 - `"/v1/chat/completions"`

319

320 - `"/v1/embeddings"`

321

322 - `"/v1/completions"`

323

324 - `"/v1/moderations"`

325

326 - `"/v1/images/generations"`

327

328 - `"/v1/images/edits"`

329

330 - `"/v1/videos"`

331

332- `input_file_id: string`

333

334 The ID of an uploaded file that contains requests for the new batch.

335

336 See [upload file](/docs/api-reference/files/create) for how to upload a file.

337

338 Your input file must be formatted as a [JSONL file](/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 200 MB in size.

339

340- `metadata: optional Metadata`

341

342 Set of 16 key-value pairs that can be attached to an object. This can be

343 useful for storing additional information about the object in a structured

344 format, and querying for objects via API or the dashboard.

345

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

347 with a maximum length of 512 characters.

348

349- `output_expires_after: optional object { anchor, seconds }`

350

351 The expiration policy for the output and/or error file that are generated for a batch.

352

353 - `anchor: "created_at"`

354

355 Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`. Note that the anchor is the file creation time, not the time the batch is created.

356

357 - `"created_at"`

358

359 - `seconds: number`

360

361 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

371 362

372### Returns363### Returns

373 364

551### Example542### Example

552 543

553```http544```http

554curl https://api.openai.com/v1/batches/$BATCH_ID \545curl https://api.openai.com/v1/batches \

555 -H "Authorization: Bearer $OPENAI_API_KEY"546 -H 'Content-Type: application/json' \

547 -H "Authorization: Bearer $OPENAI_API_KEY" \

548 -d '{

549 "completion_window": "24h",

550 "endpoint": "/v1/responses",

551 "input_file_id": "input_file_id"

552 }'

556```553```

557 554

558#### Response555#### Response

613### Example610### Example

614 611

615```http612```http

616curl https://api.openai.com/v1/batches/batch_abc123 \613curl https://api.openai.com/v1/batches \

617 -H "Authorization: Bearer $OPENAI_API_KEY" \614 -H "Authorization: Bearer $OPENAI_API_KEY" \

618 -H "Content-Type: application/json" \615 -H "Content-Type: application/json" \

616 -d '{

617 "input_file_id": "file-abc123",

618 "endpoint": "/v1/chat/completions",

619 "completion_window": "24h"

620 }'

619```621```

620 622

621#### Response623#### Response

624{626{

625 "id": "batch_abc123",627 "id": "batch_abc123",

626 "object": "batch",628 "object": "batch",

627 "endpoint": "/v1/completions",629 "endpoint": "/v1/chat/completions",

628 "errors": null,630 "errors": null,

629 "input_file_id": "file-abc123",631 "input_file_id": "file-abc123",

630 "completion_window": "24h",632 "completion_window": "24h",

631 "status": "completed",633 "status": "validating",

632 "output_file_id": "file-cvaTdG",634 "output_file_id": null,

633 "error_file_id": "file-HOWS94",635 "error_file_id": null,

634 "created_at": 1711471533,636 "created_at": 1711471533,

635 "in_progress_at": 1711471538,637 "in_progress_at": null,

636 "expires_at": 1711557933,638 "expires_at": null,

637 "finalizing_at": 1711493133,639 "finalizing_at": null,

638 "completed_at": 1711493163,640 "completed_at": null,

639 "failed_at": null,641 "failed_at": null,

640 "expired_at": null,642 "expired_at": null,

641 "cancelling_at": null,643 "cancelling_at": null,

642 "cancelled_at": null,644 "cancelled_at": null,

643 "request_counts": {645 "request_counts": {

644 "total": 100,646 "total": 0,

645 "completed": 95,647 "completed": 0,

646 "failed": 5648 "failed": 0

647 },649 },

648 "metadata": {650 "metadata": {

649 "customer_id": "user_123456789",651 "customer_id": "user_123456789",

652}654}

653```655```

654 656

655## Cancel batch657## List batches

656 658

657**post** `/batches/{batch_id}/cancel`659**get** `/batches`

658 660

659Cancels 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.661List your organization's batches.

660 662

661### Path Parameters663### Query Parameters

662 664

663- `batch_id: string`665- `after: optional string`

666

667 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.

668

669- `limit: optional number`

670

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

664 672

665### Returns673### Returns

666 674

667- `Batch object { id, completion_window, created_at, 19 more }`675- `data: array of Batch`

668 676

669 - `id: string`677 - `id: string`

670 678

841 849

842 The total number of tokens used.850 The total number of tokens used.

843 851

852- `has_more: boolean`

853

854- `object: "list"`

855

856 - `"list"`

857

858- `first_id: optional string`

859

860- `last_id: optional string`

861

844### Example862### Example

845 863

846```http864```http

847curl https://api.openai.com/v1/batches/$BATCH_ID/cancel \865curl https://api.openai.com/v1/batches \

848 -X POST \

849 -H "Authorization: Bearer $OPENAI_API_KEY"866 -H "Authorization: Bearer $OPENAI_API_KEY"

850```867```

851 868

853 870

854```json871```json

855{872{

873 "data": [

874 {

856 "id": "id",875 "id": "id",

857 "completion_window": "completion_window",876 "completion_window": "completion_window",

858 "created_at": 0,877 "created_at": 0,

901 },920 },

902 "total_tokens": 0921 "total_tokens": 0

903 }922 }

923 }

924 ],

925 "has_more": true,

926 "object": "list",

927 "first_id": "batch_abc123",

928 "last_id": "batch_abc456"

904}929}

905```930```

906 931

907### Example932### Example

908 933

909```http934```http

910curl https://api.openai.com/v1/batches/batch_abc123/cancel \935curl https://api.openai.com/v1/batches?limit=2 \

911 -H "Authorization: Bearer $OPENAI_API_KEY" \936 -H "Authorization: Bearer $OPENAI_API_KEY" \

912 -H "Content-Type: application/json" \937 -H "Content-Type: application/json"

913 -X POST

914```938```

915 939

916#### Response940#### Response

917 941

918```json942```json

919{943{

944 "object": "list",

945 "data": [

946 {

920 "id": "batch_abc123",947 "id": "batch_abc123",

921 "object": "batch",948 "object": "batch",

922 "endpoint": "/v1/chat/completions",949 "endpoint": "/v1/chat/completions",

923 "errors": null,950 "errors": null,

924 "input_file_id": "file-abc123",951 "input_file_id": "file-abc123",

925 "completion_window": "24h",952 "completion_window": "24h",

926 "status": "cancelling",953 "status": "completed",

927 "output_file_id": null,954 "output_file_id": "file-cvaTdG",

928 "error_file_id": null,955 "error_file_id": "file-HOWS94",

929 "created_at": 1711471533,956 "created_at": 1711471533,

930 "in_progress_at": 1711471538,957 "in_progress_at": 1711471538,

931 "expires_at": 1711557933,958 "expires_at": 1711557933,

932 "finalizing_at": null,959 "finalizing_at": 1711493133,

933 "completed_at": null,960 "completed_at": 1711493163,

934 "failed_at": null,961 "failed_at": null,

935 "expired_at": null,962 "expired_at": null,

936 "cancelling_at": 1711475133,963 "cancelling_at": null,

937 "cancelled_at": null,964 "cancelled_at": null,

938 "request_counts": {965 "request_counts": {

939 "total": 100,966 "total": 100,

940 "completed": 23,967 "completed": 95,

941 "failed": 1968 "failed": 5

942 },969 },

943 "metadata": {970 "metadata": {

944 "customer_id": "user_123456789",971 "customer_id": "user_123456789",

945 "batch_description": "Nightly eval job",972 "batch_description": "Nightly job",

946 }973 }

974 },

975 { ... },

976 ],

977 "first_id": "batch_abc123",

978 "last_id": "batch_abc456",

979 "has_more": true

947}980}

948```981```

949 982

950## List batches983## Retrieve batch

~~951~~

952**get** `/batches`

~~953~~

954List your organization's batches.

~~955~~

956### Query Parameters

957 984

958- `after: optional string`985**get** `/batches/{batch_id}`

959 986

960 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.987Retrieves a batch.

961 988

962- `limit: optional number`989### Path Parameters

963 990

964 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.991- `batch_id: string`

965 992

966### Returns993### Returns

967 994

968- `data: array of Batch`995- `Batch object { id, completion_window, created_at, 19 more }`

969 996

970 - `id: string`997 - `id: string`

971 998

1142 1169

1143 The total number of tokens used.1170 The total number of tokens used.

1144 1171

1145- `has_more: boolean`

~~1146~~

1147- `object: "list"`

~~1148~~

1149 - `"list"`

~~1150~~

1151- `first_id: optional string`

~~1152~~

1153- `last_id: optional string`

~~1154~~

1155### Example1172### Example

1156 1173

1157```http1174```http

1158curl https://api.openai.com/v1/batches \1175curl https://api.openai.com/v1/batches/$BATCH_ID \

1159 -H "Authorization: Bearer $OPENAI_API_KEY"1176 -H "Authorization: Bearer $OPENAI_API_KEY"

1160```1177```

1161 1178

1163 1180

1164```json1181```json

1165{1182{

1166 "data": [

1167 {

1168 "id": "id",1183 "id": "id",

1169 "completion_window": "completion_window",1184 "completion_window": "completion_window",

1170 "created_at": 0,1185 "created_at": 0,

1213 },1228 },

1214 "total_tokens": 01229 "total_tokens": 0

1215 }1230 }

1216 }

1217 ],

1218 "has_more": true,

1219 "object": "list",

1220 "first_id": "batch_abc123",

1221 "last_id": "batch_abc456"

1222}1231}

1223```1232```

1224 1233

1225### Example1234### Example

1226 1235

1227```http1236```http

1228curl https://api.openai.com/v1/batches?limit=2 \1237curl https://api.openai.com/v1/batches/batch_abc123 \

1229 -H "Authorization: Bearer $OPENAI_API_KEY" \1238 -H "Authorization: Bearer $OPENAI_API_KEY" \

1230 -H "Content-Type: application/json"1239 -H "Content-Type: application/json" \

1231```1240```

1232 1241

1233#### Response1242#### Response

1234 1243

1235```json1244```json

1236{1245{

1237 "object": "list",

1238 "data": [

1239 {

1240 "id": "batch_abc123",1246 "id": "batch_abc123",

1241 "object": "batch",1247 "object": "batch",

1242 "endpoint": "/v1/chat/completions",1248 "endpoint": "/v1/completions",

1243 "errors": null,1249 "errors": null,

1244 "input_file_id": "file-abc123",1250 "input_file_id": "file-abc123",

1245 "completion_window": "24h",1251 "completion_window": "24h",

1262 },1268 },

1263 "metadata": {1269 "metadata": {

1264 "customer_id": "user_123456789",1270 "customer_id": "user_123456789",

1265 "batch_description": "Nightly job",1271 "batch_description": "Nightly eval job",

1266 }1272 }

1267 },

1268 { ... },

1269 ],

1270 "first_id": "batch_abc123",

1271 "last_id": "batch_abc456",

1272 "has_more": true

1273}1273}

1274```1274```

1275 1275

resources/batches/index.md 2026-07-25 05:59 UTC to 2026-07-29 15:02 UTC

Batches

Cancel batch

Path Parameters

Returns

Example

Response

Example

Response

Create batch

Body Parameters

Returns

Example

Response

Example

Response

List batches

Query Parameters

Returns

Example

Response

Example

Response

Retrieve batch

Path Parameters

Returns

Example

Response

Example

Response

Domain Types

Batch

Batch Error

Batch Request Counts

Batch Usage