Skip to content
Hayonix

API reference · Batches

List the lines of a batch in input order: status, error, tokens and cost

GET/v1/batches/{batch_id}/lines
API keybatch:readProjectPaginated
TypeScript
client.batches.listLines()
Python
client.batches.list_lines()
CLI
hayonix batches lines

One entry per request line of the input file, in line order, once the batch is validated. Use it to follow a batch line by line, or to find the lines that failed (status=failed) without downloading the error file. Response bodies are in the output file.

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/bat_01jc5zq4m8k3v6x9t2w7r0b1e4/lines" \
  -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.

Path parameters

  • batch_idstringrequired

    ID of the batch

    ID with prefix bat_

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • statusstring

    Only lines in this status (default: every line)

    One ofpendingrunningcompletedfailed

Response

200 a page of results — A page of lines

  • dataarray of BatchLinerequired

    The items of this page.

    Show 13 fields of data
    • objectstringrequired

      Always `batch_line`: the type of this object

      One ofbatch_line

    • lineintegerrequired

      Line number in the input file, from 1

    • custom_idstringrequired

      The `custom_id` the line carries

    • modelstring | nullrequired

      Model the line names (null when the line could not be read)

    • statusstringrequired

      `pending` (waiting to run, or waiting to be retried), `running`, `completed` (a response is in the output file), `failed` (an error is in the error file)

      One ofpendingrunningcompletedfailed

    • status_codeinteger | nullrequired

      HTTP status of the recorded result (null until there is one)

    • errorobject | nullrequired

      Why the line failed (null unless `status` is `failed`)

      Show 2 fields of error
      • codestringrequired

        Machine-readable reason, as in the error file

      • messagestringrequired

        One sentence for people

    • last_errorobject | nullrequired

      Why the latest attempt was put back to be retried (for example `model_unavailable` while the model has no running replica); null when none was

      Show 2 fields of last_error
      • codestringrequired

        Machine-readable reason, as in the error file

      • messagestringrequired

        One sentence for people

    • attemptsintegerrequired

      Times the request was sent; retries after a failure count

    • usageobject | nullrequired

      Tokens of the completed request (null until it completes)

      Show 3 fields of usage
      • input_tokensstringrequired

        Prompt tokens (decimal string)

      • cached_input_tokensstringrequired

        Prompt tokens served from cache (decimal string)

      • output_tokensstringrequired

        Generated tokens (decimal string)

    • coststring | nullrequired

      Charged for this line, nano-USD (null until it completes; failures cost 0)

      pattern ^-?[0-9]+$

    • started_atstring (date-time) | nullrequired

      When its current attempt started (null until it ran)

    • finished_atstring (date-time) | nullrequired

      When it completed or failed (null until then)

  • next_cursorstring | nullrequired

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

Example response
Example response
{
  "data": [
    {
      "object": "batch_line",
      "line": 1,
      "custom_id": "string",
      "model": "string",
      "status": "pending",
      "status_code": 1,
      "error": {
        "code": "string",
        "message": "string"
      },
      "last_error": {
        "code": "string",
        "message": "string"
      },
      "attempts": 1,
      "usage": {
        "input_tokens": "string",
        "cached_input_tokens": "string",
        "output_tokens": "string"
      },
      "cost": "1500000000",
      "started_at": "2026-01-01T00:00:00.000Z",
      "finished_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "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.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.