Batch - ScaleDown

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:

custom_id

string

required

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

method

string

required

Always "POST".

url

string

required

Always "/v1/chat/completions".

body

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"`

body.text

string

required

The input text to extract entities from.

body.entities

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"
}

body.instruction

string

Optional additional instructions appended to the extraction prompt.

`"model": "summarize"`

body.text

string

required

The input text to summarize.

body.instructions

string

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

body.max_tokens

number

default:20048

Maximum tokens in the generated summary.

`"model": "classify"`

body.text

string

required

The input text to classify.

body.labels

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?"}
]

body.system_prompt

string

Optional additional instructions for the classification model.

Response

{
  "batch_id": "batch-abc123",
  "status": "queued",
  "total_count": 3
}

Get batch status

`GET /v1/batches/{batch_id}`

Poll this endpoint until status is "completed" or "failed".

{
  "batch_id": "batch-abc123",
  "status": "completed",
  "total_count": 3,
  "completed_count": 3,
  "failed_count": 0
}

Get batch output

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

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

custom_id

string

The custom_id you provided in the input.

response

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.

error

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.
`401 Unauthorized`	Missing or invalid `x-api-key`.
`503 Service Unavailable`	Batch router is not configured.
`502 Bad Gateway`	Upstream batch router 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

Response:

{
  "batch_id": "batch-abc123",
  "status": "queued",
  "total_count": 3
}

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)

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']}")

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}

​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