Batch

Overview

The Batch API accepts the same request fields as the realtime endpoints. Set "model" to "extract", "summarize", or "classify" to select the operation. Each item is processed independently — a failure on one item does not affect others. Documents (document / document_mime_type) are not supported in batch requests. Pass pre-extracted text in the text field.

Submit a batch

`POST /v1/batches`

Submit a JSONL body where each line is one request. Returns a batch ID to poll for status and output. Request headers

Header	Value
`content-type`	`application/jsonl` (recommended) or `application/json`
`x-api-key`	Your API key

The body is parsed as newline-delimited JSON regardless of content-type. You can send a single JSON object (one item) or a multi-line JSONL file. JSONL line schema Each line must be a JSON object with these top-level fields:

string

required

A unique identifier for this item, assigned by you. Returned as-is in the output so you can match results to inputs.

string

required

Always "POST".

string

required

Always "/v1/chat/completions".

object

required

The request body. model is the discriminator — set it to "extract", "summarize", or "classify". Remaining fields depend on the model.

Body fields by model

`"model": "extract"`

string

required

The input text to extract entities from.

object

required

A map of entity label → plain-English description. Keys become entity type values in the response.

{
  "company": "Name of the company",
  "revenue": "Revenue figure including currency and period"
}

string

Optional additional instructions appended to the extraction prompt.

`"model": "summarize"`

string

required

The input text to summarize.

string

Optional additional rules appended to the base summarization prompt (e.g. "Use bullet points.", "Focus on financial figures only.").

number

default:20048

Maximum tokens in the generated summary.

`"model": "classify"`

string

required

The input text to classify.

array

required

Array of label objects. Each object must have:

name (string) — the label name
rubric (string) — a yes/no question describing what this label means

[
  {"name": "Positive", "rubric": "Does this text express satisfaction or approval?"},
  {"name": "Negative", "rubric": "Does this text express dissatisfaction or complaints?"}
]

string

Optional additional instructions for the classification model.

Limits A single batch may contain at most 50 requests. Submitting more returns 400. Split larger workloads across multiple batches.

Response

Returns an OpenAI-compatible Batch object. A newly created batch starts in "validating".

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": null,
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1782819284,
  "request_counts": { "total": 3, "completed": 0, "failed": 0 },
  "metadata": null
}

Get batch status

`GET /v1/batches/{batch_id}`

Poll this endpoint until status is "completed" or "failed". Returns the same OpenAI-compatible Batch object.

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "batch_abc123_output",
  "error_file_id": null,
  "created_at": 1782819284,
  "request_counts": { "total": 3, "completed": 3, "failed": 0 },
  "metadata": null
}

status is one of validating, in_progress, completed, or failed. An unknown batch ID returns 404.

Get batch output

`GET /v1/batches/{batch_id}/output`

Returns a JSONL file where each line corresponds to one input item.

string

The custom_id you provided in the input.

object | null

The response object. null if the item failed.

status_code — HTTP status of the individual item
body — ChatCompletion-shaped object. The domain result is JSON-serialized in choices[0].message.content.

object | null

Error details if the item failed. null on success.

Parsing the domain result:

import json

for line in output_text.strip().splitlines():
    item = json.loads(line)
    content = json.loads(item["response"]["body"]["choices"][0]["message"]["content"])
    # content is now the domain response dict (summary, entities, top_label, etc.)

Error responses

Status	Meaning
`400 Bad Request`	A JSONL line has an invalid `model` value or malformed JSON, or the batch exceeds 50 requests.
`401 Unauthorized`	Missing or invalid `x-api-key`.
`404 Not Found`	The batch ID does not exist, or its output is not yet available.
`502 Bad Gateway`	The batch backend request failed.

Examples

Submit a mixed batch

curl -X POST https://api.scaledown.xyz/v1/batches \
  -H "content-type: application/jsonl" \
  -H "x-api-key: <your-api-key>" \
  --data-binary @- <<'EOF'
{"custom_id":"sum-1","method":"POST","url":"/v1/chat/completions","body":{"model":"summarize","text":"Artificial intelligence is the simulation of human intelligence processes by machines...","instructions":"Use bullet points."}}
{"custom_id":"ext-1","method":"POST","url":"/v1/chat/completions","body":{"model":"extract","text":"Apple Inc. reported Q1 revenue of $94.8B. CEO Tim Cook made the announcement on Feb 1st.","entities":{"company":"Name of the company","revenue":"Revenue figure","ceo":"Name of the CEO"}}}
{"custom_id":"cls-1","method":"POST","url":"/v1/chat/completions","body":{"model":"classify","text":"This product is fantastic — fast shipping and great quality!","labels":[{"name":"Positive","rubric":"Does this text express satisfaction, praise, or approval?"},{"name":"Negative","rubric":"Does this text express dissatisfaction, complaints, or criticism?"}]}}
EOF

import json
import requests

lines = [
    {
        "custom_id": "sum-1",
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": {
            "model": "summarize",
            "text": "Artificial intelligence is the simulation of human intelligence...",
            "instructions": "Use bullet points.",
        },
    },
    {
        "custom_id": "ext-1",
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": {
            "model": "extract",
            "text": "Apple Inc. reported Q1 revenue of $94.8B. CEO Tim Cook made the announcement on Feb 1st.",
            "entities": {
                "company": "Name of the company",
                "revenue": "Revenue figure",
                "ceo": "Name of the CEO",
            },
        },
    },
    {
        "custom_id": "cls-1",
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": {
            "model": "classify",
            "text": "This product is fantastic — fast shipping and great quality!",
            "labels": [
                {"name": "Positive", "rubric": "Does this text express satisfaction, praise, or approval?"},
                {"name": "Negative", "rubric": "Does this text express dissatisfaction, complaints, or criticism?"},
            ],
        },
    },
]

body = "\n".join(json.dumps(line) for line in lines).encode()

response = requests.post(
    "https://api.scaledown.xyz/v1/batches",
    headers={
        "content-type": "application/jsonl",
        "x-api-key": "<your-api-key>",
    },
    data=body,
)
batch_id = response.json()["id"]
print(f"Batch submitted: {batch_id}")

const lines = [
  {
    custom_id: "sum-1",
    method: "POST",
    url: "/v1/chat/completions",
    body: {
      model: "summarize",
      text: "Artificial intelligence is the simulation of human intelligence...",
      instructions: "Use bullet points.",
    },
  },
  {
    custom_id: "ext-1",
    method: "POST",
    url: "/v1/chat/completions",
    body: {
      model: "extract",
      text: "Apple Inc. reported Q1 revenue of $94.8B. CEO Tim Cook made the announcement on Feb 1st.",
      entities: {
        company: "Name of the company",
        revenue: "Revenue figure",
        ceo: "Name of the CEO",
      },
    },
  },
  {
    custom_id: "cls-1",
    method: "POST",
    url: "/v1/chat/completions",
    body: {
      model: "classify",
      text: "This product is fantastic — fast shipping and great quality!",
      labels: [
        { name: "Positive", rubric: "Does this text express satisfaction, praise, or approval?" },
        { name: "Negative", rubric: "Does this text express dissatisfaction, complaints, or criticism?" },
      ],
    },
  },
];

const body = lines.map((l) => JSON.stringify(l)).join("\n");

const response = await fetch("https://api.scaledown.xyz/v1/batches", {
  method: "POST",
  headers: {
    "content-type": "application/jsonl",
    "x-api-key": "<your-api-key>",
  },
  body,
});
const { id: batch_id } = await response.json();
console.log(`Batch submitted: ${batch_id}`);

Response:

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1782819284,
  "request_counts": { "total": 3, "completed": 0, "failed": 0 },
  "metadata": null
}

Poll for completion

import time
import requests

headers = {"x-api-key": "<your-api-key>"}

while True:
    status = requests.get(
        f"https://api.scaledown.xyz/v1/batches/{batch_id}",
        headers=headers,
    ).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(5)

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

while (true) {
  const res = await fetch(`https://api.scaledown.xyz/v1/batches/${batchId}`, {
    headers: { "x-api-key": "<your-api-key>" },
  });
  const status = await res.json();
  if (status.status === "completed" || status.status === "failed") break;
  await sleep(5000);
}

Retrieve and parse output

import json
import requests

response = requests.get(
    f"https://api.scaledown.xyz/v1/batches/{batch_id}/output",
    headers={"x-api-key": "<your-api-key>"},
)

for line in response.text.strip().splitlines():
    item = json.loads(line)
    model = item["response"]["body"]["model"]
    content = json.loads(item["response"]["body"]["choices"][0]["message"]["content"])

    if model == "summarize":
        print(f"[{item['custom_id']}] Summary: {content['summary']}")
    elif model == "extract":
        for entity in content["entities"]:
            print(f"[{item['custom_id']}] {entity['type']}: {entity['value']}")
    elif model == "classify":
        print(f"[{item['custom_id']}] Top label: {content['top_label']} — {content['reasoning']}")

const outputRes = await fetch(
  `https://api.scaledown.xyz/v1/batches/${batchId}/output`,
  { headers: { "x-api-key": "<your-api-key>" } }
);
const text = await outputRes.text();

for (const line of text.trim().split("\n")) {
  const item = JSON.parse(line);
  const body = item.response.body;
  const content = JSON.parse(body.choices[0].message.content);

  if (body.model === "summarize") {
    console.log(`[${item.custom_id}] Summary:`, content.summary);
  } else if (body.model === "extract") {
    for (const entity of content.entities) {
      console.log(`[${item.custom_id}] ${entity.type}: ${entity.value}`);
    }
  } else if (body.model === "classify") {
    console.log(`[${item.custom_id}] Top label: ${content.top_label} — ${content.reasoning}`);
  }
}

Sample output JSONL:

{"custom_id":"sum-1","response":{"status_code":200,"body":{"model":"summarize","choices":[{"message":{"content":"{\"summary\":\"• AI simulates human cognitive processes in machines.\\n• Key research areas include learning, reasoning, and perception.\",\"input_chars\":420,\"output_chars\":112}"}}]}},"error":null}
{"custom_id":"ext-1","response":{"status_code":200,"body":{"model":"extract","choices":[{"message":{"content":"{\"entities\":[{\"type\":\"company\",\"value\":\"Apple Inc.\",\"score\":0.98},{\"type\":\"revenue\",\"value\":\"$94.8B\",\"score\":0.97},{\"type\":\"ceo\",\"value\":\"Tim Cook\",\"score\":0.99}]}"}}]}},"error":null}
{"custom_id":"cls-1","response":{"status_code":200,"body":{"model":"classify","choices":[{"message":{"content":"{\"top_label\":\"Positive\",\"scores\":{\"Positive\":0.97,\"Negative\":0.03},\"reasoning\":\"The text praises fast shipping and product quality explicitly.\"}"}}]}},"error":null}

Getting Started

Compress

Summarize

Extract

Classify

Batch

Overview

Submit a batch

`POST /v1/batches`

Body fields by model

`"model": "extract"`

`"model": "summarize"`

`"model": "classify"`

Response

Get batch status

`GET /v1/batches/{batch_id}`

Get batch output

`GET /v1/batches/{batch_id}/output`

Error responses

Examples

Submit a mixed batch

Poll for completion

Retrieve and parse output

​Overview

​Submit a batch

​POST /v1/batches

​Body fields by model

​"model": "extract"

​"model": "summarize"

​"model": "classify"

​Response

​Get batch status

​GET /v1/batches/{batch_id}

​Get batch output

​GET /v1/batches/{batch_id}/output

​Error responses

​Examples

​Submit a mixed batch

​Poll for completion

​Retrieve and parse output

Overview

Submit a batch

`POST /v1/batches`

Body fields by model

`"model": "extract"`

`"model": "summarize"`

`"model": "classify"`

Response

Get batch status

`GET /v1/batches/{batch_id}`

Get batch output

`GET /v1/batches/{batch_id}/output`

Error responses

Examples

Submit a mixed batch

Poll for completion

Retrieve and parse output