Skip to main content

Batches

Asynchronous bulk chat completions and their JSONL input files. Reference for API version 2026-11-11.

On this page
CurrentDownload OpenAPI (JSON)Versioning

List batches

GET /api/v1/llm/v1/batches

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Query parameters

  • limit integer
    Default
    20
    Minimum
    1
    Maximum
    100

Responses

  • 200 The caller's batches, newest first.

    application/json

    Body (application/json)

    • object string
      Always
      list
    • data array of objects
      11 fields in data
      • id string
      • object string
        Always
        batch
      • endpoint string
      • status string
        One of
        pending running done expired failed canceled
      • completion_window string
      • request_counts object
        3 fields in request_counts
        • total integer
        • completed integer
        • failed integer
      • output_file_id string or null
      • error_file_id string or null
      • input_file_id string or null
      • created_at integer or string or null
      • metadata object or null
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope

Example

cURL
curl "https://api.breachline.io/api/v1/llm/v1/batches" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "batch",
      "endpoint": "string",
      "status": "pending",
      "completion_window": "string",
      "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
      },
      "output_file_id": "string",
      "error_file_id": "string",
      "input_file_id": "string",
      "created_at": 0,
      "metadata": {}
    }
  ]
}

Create a batch

POST /api/v1/llm/v1/batches

Submit up to 50,000 chat completion requests, inline (requests) or as an uploaded JSONL file (input_file_id). Batches need an organization-bound user and the llm:batch, llm:chat or llm:access scope. They are charged once, at the full Nebula price, when final results are fetched.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Request body

application/json Required

  • requests array of objects
    Maximum items
    50000
    4 fields in requests
    • custom_id string
    • method string
      Always
      POST
    • url string
      Always
      /v1/chat/completions
    • body object
      14 fields in body
      • model string

        nebula-4.5 (text, smart-routed) or nebula-v (vision). Unknown and retired ids resolve to nebula-4.5.

        Default
        nebula-4.5
      • messages array of objects Required
        5 fields in messages
        • role string Required
          One of
          system user assistant tool
        • content string or array of objects or null

          Text, or an array of content parts (text, and image_url for nebula-v).

        • name string or null
        • tool_calls array of objects or null
          3 fields in tool_calls
          • id string
          • type string
            Always
            function
          • function object
        • tool_call_id string or null

          For role: tool, the id of the call being answered.

      • max_tokens integer or null

        Output-token ceiling. An explicit value is clamped to the platform maximum.

        Minimum
        1
      • max_completion_tokens integer or null

        Alias of max_tokens; when both are sent, the smaller wins.

        Minimum
        1
      • temperature number or null
        Default
        0.7
        Minimum
        0
        Maximum
        2
      • top_p number or null
        Default
        1
        Minimum
        0
        Maximum
        1
      • stream boolean or null
        Default
        false
      • stop string or array of strings or null
      • tools array of objects or null

        OpenAI-format function tool definitions.

      • tool_choice string or object or null

        auto, none, required, or { "type": "function", "function": { "name": … } }.

      • parallel_tool_calls boolean or null
      • response_format object or null

        { "type": "json_object" } or { "type": "json_schema", "json_schema": { … } }.

      • reasoning_effort string or null

        Requested reasoning depth. Omit it for adaptive routing.

        One of
        none low medium high max xhigh ultra null
      • user string or null

        A stable session or end-user id. Send the same value on every turn of a conversation so prompt caching can reuse earlier context.

  • input_file_id string

    A JSONL file uploaded with POST /api/v1/llm/v1/files.

  • endpoint string
    Always
    /v1/chat/completions
  • completion_window string
    Default
    24h

Responses

  • 200 The created batch.

    application/json

    Body (application/json)

    • id string
    • object string
      Always
      batch
    • endpoint string
    • status string
      One of
      pending running done expired failed canceled
    • completion_window string
    • request_counts object
      3 fields in request_counts
      • total integer
      • completed integer
      • failed integer
    • output_file_id string or null
    • error_file_id string or null
    • input_file_id string or null
    • created_at integer or string or null
    • metadata object or null
  • 400 The request was malformed or failed a server-side check.Error envelope
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 404 The resource does not exist or is not visible to this caller.Error envelope

Example

cURL
curl -X POST "https://api.breachline.io/api/v1/llm/v1/batches" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Example 200 response
{
  "id": "string",
  "object": "batch",
  "endpoint": "string",
  "status": "pending",
  "completion_window": "string",
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "output_file_id": "string",
  "error_file_id": "string",
  "input_file_id": "string",
  "created_at": 0,
  "metadata": {}
}

Retrieve a batch

GET /api/v1/llm/v1/batches/{batch_id}

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Path parameters

  • batch_id string Required

Responses

  • 200 The batch and its request counts.

    application/json

    Body (application/json)

    • id string
    • object string
      Always
      batch
    • endpoint string
    • status string
      One of
      pending running done expired failed canceled
    • completion_window string
    • request_counts object
      3 fields in request_counts
      • total integer
      • completed integer
      • failed integer
    • output_file_id string or null
    • error_file_id string or null
    • input_file_id string or null
    • created_at integer or string or null
    • metadata object or null
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 404 The resource does not exist or is not visible to this caller.Error envelope

Example

cURL
curl "https://api.breachline.io/api/v1/llm/v1/batches/{batch_id}" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "id": "string",
  "object": "batch",
  "endpoint": "string",
  "status": "pending",
  "completion_window": "string",
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "output_file_id": "string",
  "error_file_id": "string",
  "input_file_id": "string",
  "created_at": 0,
  "metadata": {}
}

Cancel a batch

POST /api/v1/llm/v1/batches/{batch_id}/cancel

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Path parameters

  • batch_id string Required

Responses

  • 200 The batch after the cancel request.

    application/json

    Body (application/json)

    • id string
    • object string
      Always
      batch
    • endpoint string
    • status string
      One of
      pending running done expired failed canceled
    • completion_window string
    • request_counts object
      3 fields in request_counts
      • total integer
      • completed integer
      • failed integer
    • output_file_id string or null
    • error_file_id string or null
    • input_file_id string or null
    • created_at integer or string or null
    • metadata object or null
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 404 The resource does not exist or is not visible to this caller.Error envelope

Example

cURL
curl -X POST "https://api.breachline.io/api/v1/llm/v1/batches/{batch_id}/cancel" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
{
  "id": "string",
  "object": "batch",
  "endpoint": "string",
  "status": "pending",
  "completion_window": "string",
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "output_file_id": "string",
  "error_file_id": "string",
  "input_file_id": "string",
  "created_at": 0,
  "metadata": {}
}

Get batch results

GET /api/v1/llm/v1/batches/{batch_id}/results

One result per request. The batch is charged once, when its results are first fetched in a final state. While that charge is not yet settled the endpoint answers 503 with Retry-After: 30.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Path parameters

  • batch_id string Required

Responses

  • 200 The results.

    application/json

    Body (application/json)

    • custom_id string
    • response object
    • error object or null
  • 400 The request was malformed or failed a server-side check.Error envelope
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 404 The resource does not exist or is not visible to this caller.Error envelope
  • 502 A dependency is temporarily unavailable. Retry with backoff; honour Retry-After when present.Error envelope
  • 503 A dependency is temporarily unavailable. Retry with backoff; honour Retry-After when present.Error envelope

Example

cURL
curl "https://api.breachline.io/api/v1/llm/v1/batches/{batch_id}/results" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"
Example 200 response
[
  {
    "custom_id": "string",
    "response": {},
    "error": {}
  }
]

Upload a batch input file

POST /api/v1/llm/v1/files

Upload a JSONL file of batch requests (multipart form, field file). Maximum 50 MiB by default.

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Request body

multipart/form-data Required

  • file file Required

    JSONL, one request per line.

  • purpose string
    Default
    batch

Responses

  • 200 The stored file.

    application/json

    Body (application/json)

    • id string
    • object string
      Always
      file
    • purpose string
    • bytes integer
    • created_at integer

      Unix seconds.

  • 400 The request was malformed or failed a server-side check.Error envelope
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 503 A dependency is temporarily unavailable. Retry with backoff; honour Retry-After when present.Error envelope

Example

cURL
curl -X POST "https://api.breachline.io/api/v1/llm/v1/files" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY" \
  -F "file=@requests.jsonl" \
  -F "purpose=batch"
Example 200 response
{
  "id": "string",
  "object": "file",
  "purpose": "string",
  "bytes": 0,
  "created_at": 0
}

Download file content

GET /api/v1/llm/v1/files/{file_id}/content

Authentication

  • API key in X-API-Key
  • API key or session token in Authorization: Bearer

Path parameters

  • file_id string Required

Responses

  • 200 The raw file bytes.application/octet-stream
  • 401 Missing, invalid, expired or revoked credentials.Error envelope
  • 403 The credential is valid but lacks a required scope or permission.Error envelope
  • 404 The resource does not exist or is not visible to this caller.Error envelope

Example

cURL
curl "https://api.breachline.io/api/v1/llm/v1/files/{file_id}/content" \
  -H "Authorization: Bearer $BREACHLINE_API_KEY"

Search documentation

Type to search guides, the API reference, the CLI and the console guide.

    Enter open↑ ↓ moveEsc close