Skip to content
Hayonix

API reference · Schema

BatchList

  • objectstringrequired

    Always `list`: the type of this object

    One oflist

  • dataarray of Batchrequired

    The items

    Show 26 fields of data
    • 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)

  • has_morebooleanrequired

    True when another page follows this one

  • first_idstring | nullrequired

    ID of the first

  • last_idstring | nullrequired

    ID of the last

  • next_cursorstring | nullrequired

    Pass as `cursor` to get the next page; null when there is no more

Example
{
  "object": "list",
  "data": [
    {
      "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"
      }
    }
  ],
  "has_more": true,
  "first_id": "string",
  "last_id": "string",
  "next_cursor": "string"
}

Used by