Batch

Download schema

A batch is an asynchronous process that executes multiple requests. It takes a file containing the requests to perform as input, and writes the results to an output file.

Files are stored within Scaleway Object Storage.

See How to use batch processingOpen in new context for code snippets using openai Python client.

List batches

GET

https://api.scaleway.ai

/{project_id}/v1/batches

List batches including their properties and status.

List batches › path Parameters

project_id

ProjectId · required

The ID of the Project you want to target. If this value is not provided, your default Project will be used.

Specifying this value allows you to limit access through IAM policies, or to allocate consumption and billing to a specific project.

List batches › query Parameters

after

string

Pagination cursor which value should be a batch UUID. When response consists of multiple pages, provide the last batch UUID obtained in previous request to fetch next page.

limit

integer · min: 0 · max: 100

Maximum number of batches to retrieve.

Default: 20

List batches › Responses

200

ListBatchResponse

object

string · enum

Type of response object, always set to list.

Enum values:

list

Batch[]

List of batches.

first_id

string

UUID of first batch in the response.

last_id

string

UUID of last batch in the response.

has_more

boolean

Defines whether there are more results to retrieve not returned by this query.

GET/{project_id}/v1/batches

curl https://api.scaleway.ai/v1/batches?limit=10 \
  -H "Authorization: Bearer $SCW_SECRET_KEY" \
  -H "Content-Type: application/json"

Example Responses

{
  "object": "list",
  "data": [
    {
      "id": "id",
      "object": "batch",
      "endpoint": "endpoint",
      "model": "model",
      "errors": {
        "object": "object",
        "data": [
          {
            "code": "code",
            "line": 0,
            "message": "message",
            "param": "param"
          }
        ]
      },
      "input_file_id": "input_file_id",
      "completion_window": "completion_window",
      "status": "status",
      "output_file_id": "output_file_id",
      "error_file_id": "error_file_id",
      "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": {
        "completed": 0,
        "failed": 0,
        "total": 0
      },
      "usage": {
        "type": "type",
        "duration": 0,
        "input_tokens": 0,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "total_tokens": 0,
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        }
      }
    }
  ],
  "first_id": "first_id",
  "last_id": "last_id",
  "has_more": true
}

json

application/json

Create a batch

POST

https://api.scaleway.ai

/{project_id}/v1/batches

Process multiple requests asynchronously in batch.

Create a batch › path Parameters

project_id

ProjectId · required

The ID of the Project you want to target. If this value is not provided, your default Project will be used.

Specifying this value allows you to limit access through IAM policies, or to allocate consumption and billing to a specific project.

Create a batch › Request Body

completion_window

required

Time range during which the batch should be processed. Currently only 24h is supported.

endpoint

required

Path to use to process requests in the batch. Currently /v1/chat/completions, /v1/responses, /v1/embeddings and /v1/audio/transcriptions are supported.

input_file_id

required

URL of the file in Scaleway Object Storage. File should contain all request to process in JSONL formatOpen in new context. Results will be stored within the same bucket and folder, and named {filename}-output.jsonl and {filename}-error.jsonl.

See How to use batch processingOpen in new context for code snippets using openai Python client.

output_expires_after

Expiration rules for the output and error files generated by the batch.

Create a batch › Responses

200

Batch

id

string

UUID of the batch.

object

string · enum

Type of batch object, always set to batch.

Enum values:

batch

endpoint

string

Path used to process requests in the batch.

model

string

Model used to process the batch

object

Error object

input_file_id

string

URL of the input file.

completion_window

string

Time range during which the batch should be processed.

status

string

Status of the batch.

output_file_id

string

URL of the input file.

error_file_id

string

URL of the input file.

created_at

integer

Timestamp when the batch was created (Unix format, in seconds).

in_progress_at

integer

Timestamp when the batch processing started (Unix format, in seconds).

expires_at

integer

Timestamp when the batch will expire (Unix format, in seconds).

finalizing_at

integer

Timestamp when the batch started finalizing (Unix format, in seconds).

completed_at

integer

Timestamp when the batch was completed (Unix format, in seconds).

failed_at

integer

Timestamp when the batch failed (Unix format, in seconds).

expired_at

integer

Timestamp when the batch expired (Unix format, in seconds).

cancelling_at

integer

Timestamp when the batch started cancelling (Unix format, in seconds).

cancelled_at

integer

Timestamp when the batch was cancelled (Unix format, in seconds).

object

Number of requests by status.

object

Usage information generated by the requests of the batch, either in tokens or duration depending on how the model is billed.

POST/{project_id}/v1/batches

curl https://api.scaleway.ai/v1/batches \
  -H "Authorization: Bearer $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "https://bucket-123.s3.fr-par.scw.cloud/folder-123/batch-123.jsonl",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

Example Request Body

{
  "completion_window": {},
  "endpoint": {},
  "input_file_id": {},
  "output_expires_after": {}
}

json

Example Responses

{
  "id": "id",
  "object": "batch",
  "endpoint": "endpoint",
  "model": "model",
  "errors": {
    "object": "object",
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ]
  },
  "input_file_id": "input_file_id",
  "completion_window": "completion_window",
  "status": "status",
  "output_file_id": "output_file_id",
  "error_file_id": "error_file_id",
  "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": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "type": "type",
    "duration": 0,
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 0,
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

json

application/json

Get a batch

GET

https://api.scaleway.ai

/{project_id}/v1/batches/{batch_id}

Retrieve a batch's properties and status.

Get a batch › path Parameters

project_id

ProjectId · required

The ID of the Project you want to target. If this value is not provided, your default Project will be used.

Specifying this value allows you to limit access through IAM policies, or to allocate consumption and billing to a specific project.

batch_id

string · required

UUID of the batch.

Get a batch › Responses

200

Batch

id

string

UUID of the batch.

object

string · enum

Type of batch object, always set to batch.

Enum values:

batch

endpoint

string

Path used to process requests in the batch.

model

string

Model used to process the batch

object

Error object

input_file_id

string

URL of the input file.

completion_window

string

Time range during which the batch should be processed.

status

string

Status of the batch.

output_file_id

string

URL of the input file.

error_file_id

string

URL of the input file.

created_at

integer

Timestamp when the batch was created (Unix format, in seconds).

in_progress_at

integer

Timestamp when the batch processing started (Unix format, in seconds).

expires_at

integer

Timestamp when the batch will expire (Unix format, in seconds).

finalizing_at

integer

Timestamp when the batch started finalizing (Unix format, in seconds).

completed_at

integer

Timestamp when the batch was completed (Unix format, in seconds).

failed_at

integer

Timestamp when the batch failed (Unix format, in seconds).

expired_at

integer

Timestamp when the batch expired (Unix format, in seconds).

cancelling_at

integer

Timestamp when the batch started cancelling (Unix format, in seconds).

cancelled_at

integer

Timestamp when the batch was cancelled (Unix format, in seconds).

object

Number of requests by status.

object

Usage information generated by the requests of the batch, either in tokens or duration depending on how the model is billed.

GET/{project_id}/v1/batches/{batch_id}

curl https://api.scaleway.ai/v1/batches/{batch_id} \
  -H "Authorization: Bearer $SCW_SECRET_KEY" \
  -H "Content-Type: application/json"

Example Responses

{
  "id": "id",
  "object": "batch",
  "endpoint": "endpoint",
  "model": "model",
  "errors": {
    "object": "object",
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ]
  },
  "input_file_id": "input_file_id",
  "completion_window": "completion_window",
  "status": "status",
  "output_file_id": "output_file_id",
  "error_file_id": "error_file_id",
  "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": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "type": "type",
    "duration": 0,
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 0,
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

json

application/json

Delete a batch

DELETE

https://api.scaleway.ai

/{project_id}/v1/batches/{batch_id}

Delete a previously created batch.

When a batch is deleted, the associated input.jsonl, output.jsonl and errors.jsonl files are not removed from the bucket.

This endpoint is a Scaleway‑specific extension that supplements the OpenAI‑compatible API; it is not part of the official OpenAI API specification.

Delete a batch › path Parameters

project_id

ProjectId · required

The ID of the Project you want to target. If this value is not provided, your default Project will be used.

Specifying this value allows you to limit access through IAM policies, or to allocate consumption and billing to a specific project.

batch_id

string · required

UUID of the batch.

Delete a batch › Responses

200

Batch

id

string

UUID of the batch.

object

string · enum

Type of batch object, always set to batch.

Enum values:

batch

endpoint

string

Path used to process requests in the batch.

model

string

Model used to process the batch

object

Error object

input_file_id

string

URL of the input file.

completion_window

string

Time range during which the batch should be processed.

status

string

Status of the batch.

output_file_id

string

URL of the input file.

error_file_id

string

URL of the input file.

created_at

integer

Timestamp when the batch was created (Unix format, in seconds).

in_progress_at

integer

Timestamp when the batch processing started (Unix format, in seconds).

expires_at

integer

Timestamp when the batch will expire (Unix format, in seconds).

finalizing_at

integer

Timestamp when the batch started finalizing (Unix format, in seconds).

completed_at

integer

Timestamp when the batch was completed (Unix format, in seconds).

failed_at

integer

Timestamp when the batch failed (Unix format, in seconds).

expired_at

integer

Timestamp when the batch expired (Unix format, in seconds).

cancelling_at

integer

Timestamp when the batch started cancelling (Unix format, in seconds).

cancelled_at

integer

Timestamp when the batch was cancelled (Unix format, in seconds).

object

Number of requests by status.

object

Usage information generated by the requests of the batch, either in tokens or duration depending on how the model is billed.

DELETE/{project_id}/v1/batches/{batch_id}

curl -X DELETE https://api.scaleway.ai/v1/batches/{batch_id} \
  -H "Authorization: Bearer $SCW_SECRET_KEY" \

Example Responses

{
  "id": "id",
  "object": "batch",
  "endpoint": "endpoint",
  "model": "model",
  "errors": {
    "object": "object",
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ]
  },
  "input_file_id": "input_file_id",
  "completion_window": "completion_window",
  "status": "status",
  "output_file_id": "output_file_id",
  "error_file_id": "error_file_id",
  "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": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "type": "type",
    "duration": 0,
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 0,
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

json

application/json

Cancel a batch

POST

https://api.scaleway.ai

/{project_id}/v1/batches/{batch_id}/cancel

When a batch is cancelled, results already processed are stored in corresponding output.jsonl and errors.jsonl files, while remaining requests will not be processed.

Cancel a batch › path Parameters

project_id

ProjectId · required

The ID of the Project you want to target. If this value is not provided, your default Project will be used.

Specifying this value allows you to limit access through IAM policies, or to allocate consumption and billing to a specific project.

batch_id

string · required

UUID of the batch.

Cancel a batch › Responses

200

Batch

id

string

UUID of the batch.

object

string · enum

Type of batch object, always set to batch.

Enum values:

batch

endpoint

string

Path used to process requests in the batch.

model

string

Model used to process the batch

object

Error object

input_file_id

string

URL of the input file.

completion_window

string

Time range during which the batch should be processed.

status

string

Status of the batch.

output_file_id

string

URL of the input file.

error_file_id

string

URL of the input file.

created_at

integer

Timestamp when the batch was created (Unix format, in seconds).

in_progress_at

integer

Timestamp when the batch processing started (Unix format, in seconds).

expires_at

integer

Timestamp when the batch will expire (Unix format, in seconds).

finalizing_at

integer

Timestamp when the batch started finalizing (Unix format, in seconds).

completed_at

integer

Timestamp when the batch was completed (Unix format, in seconds).

failed_at

integer

Timestamp when the batch failed (Unix format, in seconds).

expired_at

integer

Timestamp when the batch expired (Unix format, in seconds).

cancelling_at

integer

Timestamp when the batch started cancelling (Unix format, in seconds).

cancelled_at

integer

Timestamp when the batch was cancelled (Unix format, in seconds).

object

Number of requests by status.

object

Usage information generated by the requests of the batch, either in tokens or duration depending on how the model is billed.

POST/{project_id}/v1/batches/{batch_id}/cancel

curl https://api.scaleway.ai/v1/batches/{batch_id}/cancel \
  -H "Authorization: Bearer $SCW_SECRET_KEY" \
  -H "Content-Type: application/json"

Example Responses

{
  "id": "id",
  "object": "batch",
  "endpoint": "endpoint",
  "model": "model",
  "errors": {
    "object": "object",
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ]
  },
  "input_file_id": "input_file_id",
  "completion_window": "completion_window",
  "status": "status",
  "output_file_id": "output_file_id",
  "error_file_id": "error_file_id",
  "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": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "type": "type",
    "duration": 0,
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 0,
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

json

application/json

Audio Models