Skip to content
Hayonix

API reference · Schema

Batch

  • idstringrequired

    Unique ID (`bat_…`)

    ID with prefix bat_

  • objectstringrequired

    Always `batch`: the type of this object

    One ofbatch

  • endpointstringrequired

    The route every request goes to, such as `/v1/chat/completions`

  • modelstring | nullrequired

    The model every request names, when they all name the same one

  • errorsobject | nullrequired

    Why the batch failed (input-file problems, a billing stop)

    Show 2 fields of errors
    • objectstringrequired

      Always `list`: the type of this object

      One oflist

    • dataarray of objectrequired

      The items

      Show 4 fields of data
      • codestringrequired

        Machine-readable code

      • messagestringrequired

        One sentence for people

      • paramstring | nullrequired

        The field the error is about; null when it is not about one field

      • lineinteger | nullrequired

        1-based line of the input file; null when not about one line

  • input_file_idstringrequired

    ID of the input file

    ID with prefix file_

  • completion_windowstringrequired

    Time allowed to run every request, counted from creation; requests not run by `expires_at` are reported as failed

  • statusstringrequired

    validating → in_progress → finalizing → completed | expired | failed; cancelling → cancelled. `failed` before `in_progress` means the input file could not be run.

    One ofvalidatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled

  • output_file_idstring | nullrequired

    JSONL of the requests that succeeded (purpose `batch_output`)

  • error_file_idstring | nullrequired

    JSONL of the requests that failed or were not run

  • created_atintegerrequired

    Unix seconds (OpenAI shape)

  • in_progress_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • expires_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • finalizing_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • completed_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • failed_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • expired_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • cancelling_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • cancelled_atinteger | nullrequired

    Unix seconds (OpenAI shape)

  • request_countsobjectrequired

    Progress, counted in requests (input lines)

    Show 3 fields of request_counts
    • totalintegerrequired

      Requests in the input file; 0 until validation has finished

    • completedintegerrequired

      Requests that succeeded

    • failedintegerrequired

      Requests that were invalid or failed, plus, once the batch stops early, those never run

  • usageobjectrequired

    Tokens of the requests completed so far

    Show 5 fields of usage
    • input_tokensintegerrequired

      Prompt tokens over all completed requests

    • input_tokens_detailsobjectrequired

      Breakdown of `input_tokens`

      Show 1 field of input_tokens_details
      • cached_tokensintegerrequired

        Prompt tokens served from the prompt cache

    • output_tokensintegerrequired

      Generated tokens over all completed requests

    • output_tokens_detailsobjectrequired

      Breakdown of `output_tokens`

      Show 1 field of output_tokens_details
      • reasoning_tokensintegerrequired

        Always 0: reasoning tokens are not counted separately

    • total_tokensintegerrequired

      `input_tokens` plus `output_tokens`

  • metadataobject | nullrequired

    Your own key/value labels, returned as given

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • stop_reasonstring | nullrequired

    Why the batch stopped before running every request: cancelled, expired, insufficient_credit, spend_limit_reached, organization_suspended, api_key_revoked, billing_<reason>

  • costobjectrequired

    What the batch has cost so far

    Show 2 fields of cost
    • currencystringrequired

      Always `usd`

      One ofUSD

    • chargedstringrequired

      nano-USD charged so far for completed requests, at batch prices

      pattern ^-?[0-9]+$

  • timelineobjectrequired

    The same stage times as ISO 8601 timestamps; a stage not reached is null. `expires_at` is when the completion window ends.

    Show 9 fields of timeline
    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • in_progress_atstring (date-time) | nullrequired

      Time in progress (ISO 8601, UTC)

    • finalizing_atstring (date-time) | nullrequired

      Time finalizing (ISO 8601, UTC)

    • completed_atstring (date-time) | nullrequired

      When it completed (null until then) (ISO 8601, UTC)

    • failed_atstring (date-time) | nullrequired

      Time failed (ISO 8601, UTC)

    • expired_atstring (date-time) | nullrequired

      Time expired (ISO 8601, UTC)

    • cancelling_atstring (date-time) | nullrequired

      Time cancelling (ISO 8601, UTC)

    • cancelled_atstring (date-time) | nullrequired

      When it was cancelled (null unless it was) (ISO 8601, UTC)

    • expires_atstring (date-time)required

      When it expires (null: never) (ISO 8601, UTC)

Example
{
  "id": "bat_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "object": "batch",
  "endpoint": "string",
  "model": "string",
  "errors": {
    "object": "list",
    "data": [
      {
        "code": "string",
        "message": "string",
        "param": "string",
        "line": 1
      }
    ]
  },
  "input_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "completion_window": "string",
  "status": "validating",
  "output_file_id": "string",
  "error_file_id": "string",
  "created_at": 1,
  "in_progress_at": 1,
  "expires_at": 1,
  "finalizing_at": 1,
  "completed_at": 1,
  "failed_at": 1,
  "expired_at": 1,
  "cancelling_at": 1,
  "cancelled_at": 1,
  "request_counts": {
    "total": 1,
    "completed": 1,
    "failed": 1
  },
  "usage": {
    "input_tokens": 1,
    "input_tokens_details": {
      "cached_tokens": 1
    },
    "output_tokens": 1,
    "output_tokens_details": {
      "reasoning_tokens": 1
    },
    "total_tokens": 1
  },
  "metadata": {},
  "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "stop_reason": "string",
  "cost": {
    "currency": "USD",
    "charged": "1500000000"
  },
  "timeline": {
    "created_at": "2026-01-01T00:00:00.000Z",
    "in_progress_at": "2026-01-01T00:00:00.000Z",
    "finalizing_at": "2026-01-01T00:00:00.000Z",
    "completed_at": "2026-01-01T00:00:00.000Z",
    "failed_at": "2026-01-01T00:00:00.000Z",
    "expired_at": "2026-01-01T00:00:00.000Z",
    "cancelling_at": "2026-01-01T00:00:00.000Z",
    "cancelled_at": "2026-01-01T00:00:00.000Z",
    "expires_at": "2026-01-01T00:00:00.000Z"
  }
}

Used by