Skip to content
Hayonix

API reference · Batches

List batches in the project, newest first

GET/v1/batches
API keybatch:readProjectPaginated
TypeScript
client.batches.list()
Python
client.batches.list()
CLI
hayonix batches list

Every batch, whatever its status. Page with cursor, or with after as the official SDKs do.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the batch:read permission (a key's scope, or a role that includes it).

Examples

The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.

curl -sS "$API_BASE_URL/batches" \
  -H "Authorization: Bearer $API_KEY"

Request

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.

Query parameters

  • limitinteger

    1–200 per page, default 20

    1–10000

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • afterstring

    A batch ID: the page after it (OpenAI-style pagination)

    up to 64 characters

Response

200 BatchList — A page of batches

  • dataarray of Batchrequired

    The items of this page.

    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)

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "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"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.