Batch API

Run large async jobs across SAGEA endpoints with 50 percent discount.

POST https://api.sagea.space/v1/batch

Authentication

Send Authorization: Bearer $SAGEA_API_KEY on every request. Get a key

Parameters

Send a JSON body with the following fields.

Parameter	Type	Required	Description
`endpoint`	`string`	Yes	One of `/v1/chat/completions`, `/v1/audio/speech`, `/v1/ocr/process`, or `/helios/kyc/v1`.
`requests`	`array`	Yes	List of individual request objects for the chosen endpoint.
`callback_url`	`string`	No	HTTPS URL notified when the batch completes.
`metadata`	`object`	No	Custom key value labels for tracking your job.
`idempotency_key`	`string`	No	Unique key to safely retry batch creation.
`language`	`string`	No	Default locale hint such as `en-US`, `ne-NP`, `hi-IN`, or `es-ES`.

Example request

Batch Kathmandu summaries plus an Aarav Sharma NPR invoice check.

curl -X POST https://api.sagea.space/v1/batch \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "/v1/chat/completions",
    "requests": [
      {
        "model": "sage-2-5-celer",
        "messages": [{"role": "user", "content": "Summarize Kathmandu weather for trekkers"}]
      },
      {
        "model": "sage-2-4-actus",
        "messages": [{"role": "user", "content": "Verify invoice total NPR 24,500 for Aarav Sharma"}]
      }
    ]
  }'

Poll the returned batch_url until status is completed, then fetch results.

Response

Creation returns IDs and polling URLs for tracking progress.

{
  "batch_id": "batch_ktm24500a",
  "status": "queued",
  "endpoint": "/v1/chat/completions",
  "request_count": 2,
  "batch_url": "https://api.sagea.space/v1/batch/batch_ktm24500a",
  "results_url": "https://api.sagea.space/v1/batch/batch_ktm24500a/results",
  "discount": "50%",
  "created_at": "2026-03-12T10:00:00Z"
}

Fetch results_url after completion to download all outputs at once.

Errors

Status	Code	Fix
`400`	`invalid_request`	Check `endpoint` is one of the four allowed paths.
`401`	`unauthorized`	Re-export a valid `SAGEA_API_KEY` value.
`404`	`session_not_found`	Poll the exact `batch_url` returned on creation.
`429`	`rate_limit_exceeded`	Back off and retry with exponential delay.
`500`	`internal_error`	Retry once, then contact support with batch ID.

Limits

Batch creation follows the target endpoint limit, for example 120 per minute for Celer on Starter and 2000 per minute on Pro.