Skip to content
Hayonix

API reference · Files

List files in the project

GET/v1/files
API keyfile:readProjectPaginated
TypeScript
client.files.list()
Python
client.files.list()
CLI
hayonix files list

Newest first by default. Includes files the platform writes, such as batch output and evaluation results; filter with purpose. Page with cursor, or with after as the official SDKs do.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the file: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/files" \
  -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

  • purposestring

    Only files with this purpose

    up to 64 characters

  • limitinteger

    1–200 per page, default 50

    1–10000

  • orderstring

    By upload time; default desc

    One ofascdesc

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • afterstring

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

    up to 64 characters

Response

200 FileList — A page of files

  • dataarray of Filerequired

    The items of this page.

    Show 14 fields of data
    • idstringrequired

      Unique ID (`file_…`)

      ID with prefix file_

    • objectstringrequired

      Always `file`: the type of this object

      One offile

    • bytesintegerrequired

      Size in bytes

    • created_atintegerrequired

      Unix seconds (OpenAI shape)

    • filenamestringrequired

      The file name given at upload

    • purposestringrequired

      `fine-tune`, `batch` or `evaluation` for uploads; `batch_output` and `evaluation_results` for files the platform writes

    • statusstringrequired

      OpenAI-shaped status: processed = valid, error = invalid

      One ofuploadedprocessederror

    • status_detailsstring | nullrequired

      For an invalid file, the first error and how many more there are; null otherwise

    • expires_atinteger | nullrequired

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

    • project_idstringrequired

      Project it belongs to

      ID with prefix prj_

    • uploaded_atstring (date-time)required

      Time uploaded (ISO 8601, UTC)

    • sha256string | nullrequired

      SHA-256 of the content, hex

    • content_typestring | nullrequired

      Media type of the uploaded `file` part; null when the upload gave none

    • validationobjectrequired

      Whether the content is usable for its purpose, and why not

      Show 2 fields of validation
      • statestringrequired

        pending → running → valid | invalid

        One ofpendingrunningvalidinvalid

      • reportFileValidationReport | any JSON | nullrequired

        What validation found; null until validation has finished

        Show 15 fields of report
        • validbooleanrequired

          True when the file has no errors and can be used for its purpose

        • formatstring | nullrequired

          Detected format (every example shares one; `dataset` for evaluation data)

          One ofchatprompt_completiontextpreferencebatch_requestsdataset

        • examplesintegerrequired

          Lines holding an example, request or dataset row (blank lines are not counted)

        • linesintegerrequired

          Lines read, including blank lines

        • bytesintegerrequired

          Size in bytes

        • token_estimateintegerrequired

          Estimated tokens over all examples (characters / 4, plus template overhead)

        • max_example_token_estimateintegerrequired

          Estimated tokens of the largest single example, to compare with a model's maximum sequence length

        • token_estimate_methodstringrequired

          How token counts were estimated: characters divided by 4, rounded up

          One ofcharacters_div_4

        • error_countintegerrequired

          Errors found in the file, including those not listed in `errors`

        • errorsarray of objectrequired

          The first 100 errors, with 1-based line numbers

          Show 3 fields of errors
          • lineintegerrequired

            1-based line number in the file

          • codestringrequired

            Machine-readable code

          • messagestringrequired

            One sentence for people

        • warningsarray of stringrequired

          Problems that do not make the file invalid, such as very few training examples

        • truncatedbooleanrequired

          Validation stopped early (too many errors)

        • validated_atstring (date-time)required

          Time validated (ISO 8601, UTC)

        • datasetobject

          Evaluation datasets (purpose `evaluation`): rows and columns

          Show 6 fields of dataset
          • formatstringrequired

            JSON Lines or CSV with a header row

            One ofjsonlcsv

          • rowsintegerrequired

            Data rows (a CSV header is not counted)

          • columnsarray of stringrequired

            In order of first appearance

          • column_rowsobjectrequired

            Rows that have each column

          • column_bytesobjectrequired

            UTF-8 bytes of each column's values over all rows

          • max_row_bytesintegerrequired

            UTF-8 bytes of the largest row

        • requestsobject | nullrequired

          Batch files: the models and URLs the valid lines name, with how many lines name each, most used first. Null for training files (and for files validated before this existed).

          Show 3 fields of requests
          • modelsarray of objectrequired

            Models named in the `body.model` of valid lines

          • urlsarray of objectrequired

            Request paths named in the `url` of valid lines

          • truncatedbooleanrequired

            More than 50 distinct models or URLs: only the most used are listed

  • next_cursorstring | nullrequired

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

Example response
Example response
{
  "object": "list",
  "data": [
    {
      "id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "object": "file",
      "bytes": 1,
      "created_at": 1,
      "filename": "string",
      "purpose": "fine-tune",
      "status": "uploaded",
      "status_details": "string",
      "expires_at": 1,
      "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "uploaded_at": "2026-01-01T00:00:00.000Z",
      "sha256": "string",
      "content_type": "string",
      "validation": {
        "state": "pending",
        "report": {
          "valid": true,
          "format": "chat",
          "examples": 1,
          "lines": 1,
          "bytes": 1,
          "token_estimate": 1,
          "max_example_token_estimate": 1,
          "token_estimate_method": "characters_div_4",
          "error_count": 1,
          "errors": [
            null
          ],
          "warnings": [
            null
          ],
          "truncated": true,
          "validated_at": "2026-01-01T00:00:00.000Z",
          "dataset": {
            "format": null,
            "rows": null,
            "columns": null,
            "column_rows": null,
            "column_bytes": null,
            "max_row_bytes": null
          },
          "requests": {
            "models": null,
            "urls": null,
            "truncated": null
          }
        }
      }
    }
  ],
  "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.