Batch - OpenRouter | Documentation

Overview

Submit, list, poll, and delete asynchronous batches of inference requests. See https://openrouter.ai/docs/batch-quickstart.

Available Operations

list - List batches
createBatches - Create a batch
delete - Delete a batch
getBatches - Get a batch

list

Lists batches in the workspace of the authenticating API key, newest first. To fetch the next page, pass the previous page’s last_id as after. List items omit results. Use GET /batches/{id} to get them. See the Batch API Quickstart.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.batch.list();

  for await (const page of result) {
    console.log(page);
  }
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { batchList } from "@openrouter/sdk/funcs/batchList.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await batchList(openRouter);
  if (res.ok) {
    const { value: result } = res;
    for await (const page of result) {
    console.log(page);
  }
  } else {
    console.log("batchList failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.ListBatchesRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.ListBatchesResponse>

Errors

Error Type	Status Code	Content Type
errors.BatchErrorResponse	400, 401, 429	application/json
errors.BatchErrorResponse	500, 502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

createBatches

Creates a batch of requests that run asynchronously against a single endpoint (/v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings). Returns 202 with status: "validating". Poll GET /batches/{id} for progress and results. See the Batch API Quickstart.

Example Usage: chatCompletions

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.batch.createBatches({
    batchSubmitBody: {
      endpoint: "/v1/chat/completions",
      model: "openai/gpt-4o",
      requests: [
        {
          body: {
            "messages": [
              {
                "content": "Summarize ...",
                "role": "user",
              },
            ],
            "model": "openai/gpt-4o",
          },
          customId: "req-0001",
        },
      ],
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { batchCreateBatches } from "@openrouter/sdk/funcs/batchCreateBatches.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await batchCreateBatches(openRouter, {
    batchSubmitBody: {
      endpoint: "/v1/chat/completions",
      model: "openai/gpt-4o",
      requests: [
        {
          body: {
            "messages": [
              {
                "content": "Summarize ...",
                "role": "user",
              },
            ],
            "model": "openai/gpt-4o",
          },
          customId: "req-0001",
        },
      ],
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("batchCreateBatches failed:", res.error);
  }
}

run();

Example Usage: messages

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.batch.createBatches({
    batchSubmitBody: {
      endpoint: "/v1/messages",
      model: "openai/gpt-5-nano",
      requests: [
        {
          body: {
            "max_tokens": 1024,
            "messages": [
              {
                "content": "Summarize ...",
                "role": "user",
              },
            ],
            "model": "openai/gpt-5-nano",
          },
          customId: "req-0001",
        },
      ],
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { batchCreateBatches } from "@openrouter/sdk/funcs/batchCreateBatches.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await batchCreateBatches(openRouter, {
    batchSubmitBody: {
      endpoint: "/v1/messages",
      model: "openai/gpt-5-nano",
      requests: [
        {
          body: {
            "max_tokens": 1024,
            "messages": [
              {
                "content": "Summarize ...",
                "role": "user",
              },
            ],
            "model": "openai/gpt-5-nano",
          },
          customId: "req-0001",
        },
      ],
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("batchCreateBatches failed:", res.error);
  }
}

run();

Example Usage: providerPinned

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.batch.createBatches({
    batchSubmitBody: {
      endpoint: "/v1/chat/completions",
      model: "google/gemini-3.6-flash",
      requests: [
        {
          body: {
            "messages": [
              {
                "content": "Summarize ...",
                "role": "user",
              },
            ],
            "model": "google/gemini-3.6-flash",
          },
          customId: "req-0001",
        },
      ],
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { batchCreateBatches } from "@openrouter/sdk/funcs/batchCreateBatches.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await batchCreateBatches(openRouter, {
    batchSubmitBody: {
      endpoint: "/v1/chat/completions",
      model: "google/gemini-3.6-flash",
      requests: [
        {
          body: {
            "messages": [
              {
                "content": "Summarize ...",
                "role": "user",
              },
            ],
            "model": "google/gemini-3.6-flash",
          },
          customId: "req-0001",
        },
      ],
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("batchCreateBatches failed:", res.error);
  }
}

run();

Example Usage: responses

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.batch.createBatches({
    batchSubmitBody: {
      endpoint: "/v1/responses",
      model: "openai/gpt-4o",
      requests: [
        {
          body: {
            "input": [
              {
                "content": [
                  {
                    "text": "Summarize ...",
                    "type": "input_text",
                  },
                ],
                "role": "user",
              },
            ],
            "model": "openai/gpt-4o",
          },
          customId: "req-0001",
        },
      ],
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { batchCreateBatches } from "@openrouter/sdk/funcs/batchCreateBatches.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await batchCreateBatches(openRouter, {
    batchSubmitBody: {
      endpoint: "/v1/responses",
      model: "openai/gpt-4o",
      requests: [
        {
          body: {
            "input": [
              {
                "content": [
                  {
                    "text": "Summarize ...",
                    "type": "input_text",
                  },
                ],
                "role": "user",
              },
            ],
            "model": "openai/gpt-4o",
          },
          customId: "req-0001",
        },
      ],
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("batchCreateBatches failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.CreateBatchesRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.BatchObject>

Errors

Error Type	Status Code	Content Type
errors.BatchErrorResponse	400, 401, 402, 403, 404, 413, 422, 429	application/json
errors.BatchErrorResponse	500, 502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

delete

Deletes a batch in a terminal status (completed, failed, expired, or cancelled) and its stored requests and results. Batches still in progress return 409. Billing and usage records are kept. See the Batch API Quickstart.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.batch.delete({
    id: "batch_abc123",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { batchDelete } from "@openrouter/sdk/funcs/batchDelete.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await batchDelete(openRouter, {
    id: "batch_abc123",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("batchDelete failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.DeleteBatchRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.BatchDeletedObject>

Errors

Error Type	Status Code	Content Type
errors.BatchErrorResponse	401, 404, 409, 429	application/json
errors.BatchErrorResponse	500, 502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

getBatches

Returns a batch with its status and request counts. Batches in a terminal status include results. Failed batches report the reason in error.message. See the Batch API Quickstart.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.batch.getBatches({
    id: "batch_abc123",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { batchGetBatches } from "@openrouter/sdk/funcs/batchGetBatches.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await batchGetBatches(openRouter, {
    id: "batch_abc123",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("batchGetBatches failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.GetBatchesRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.BatchObject>

Errors

Error Type	Status Code	Content Type
errors.BatchPaymentRequiredResponseError	402	application/json
errors.BatchErrorResponse	401, 404, 429	application/json
errors.BatchErrorResponse	500, 502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

​Overview

​Available Operations

​list

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​createBatches

​Example Usage: chatCompletions

​Standalone function

​Example Usage: messages

​Standalone function

​Example Usage: providerPinned

​Standalone function

​Example Usage: responses

​Standalone function

​Parameters

​Response

​Errors

​delete

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​getBatches

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

Overview

Available Operations

list

Example Usage

Standalone function

Parameters

Response

Errors

createBatches

Example Usage: chatCompletions

Standalone function

Example Usage: messages

Standalone function

Example Usage: providerPinned

Standalone function

Example Usage: responses

Standalone function

Parameters

Response

Errors

delete

Example Usage

Standalone function

Parameters

Response

Errors

getBatches

Example Usage

Standalone function

Parameters

Response

Errors