---
title: "Batch completions"
method: POST
path: "/ai/batches"
---

# Batch completions

`POST /ai/batches`

Queue multiple LLM conversations for later retrieval.

## Request body

- object
  - `prompts` string[], required — The questions or instructions to use as chat prompts.
  - `model` 'chatgpt' | 'gemini' | 'perplexity' — The AI model to chat with.
  - `device` string — The name as returned by the [devices resource](devices) of the device to emulate chatting on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default.
  - `country` string — The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to chat from (these codes are case insensitive); a random country is used by default.
  - `subdivision` string — The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to chat from (these codes are case insensitive); a random subdivision is used by default.
  - `city` string — The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to chat from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city is used by default.
  - `language` string — [Planned] The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the language to chat in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default.
  - `display` string — [Planned] The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the chat interface’s display language (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the display language is unset by default or set to the language if given.
  - `format` 'json' | 'rendered' | 'raw (planned)' — The format to output to.
  - `expiration` integer — The age in days of when to consider a cached completion expired, where `0` disables caching.
  - `callback` string — The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the batch completions have been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.

## Response `202`

A job identifier and confirmation count.

- object
  - `id` string, uuid, required — The identifier to retrieve the batch conversations with.
  - `count` integer, required — The number of prompts in the batch as confirmed by the API.

## Other responses

- `401` — The authorization header was missing.
- `402` — No more credits are available.
- `403` — The API token was invalid.
- `422` — One or more parameters were invalid.
- `500` — An unknown error occurred.

## Changes

> 9 revisions in range; 1 could not be searched.

- **2026-07-06** `bfddf5b2c698` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/joinmassive/apis/massive/changes/ai/batches/post.md)

---

[API](https://skmtc.dev/joinmassive/apis/massive.md) · [All operations](https://skmtc.dev/joinmassive/apis/massive/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/joinmassive/massive/revisions/3a9f7769563f/schema)