Skip to content
AvraAvra
Esc
↑↓navigate↵open⌘Jpreview
On this page

Migrating to Batch v2

The v2 Batch and Files API replaces single-file batch inputs with multi-file upload sessions and batches.

The core changes to the Batch API are related to how you get data in and results out: instead of uploading one file at a time you can now upload one or more files into a session, keeping subfolder organizations and reference them when submitting a batch job as avra://uploads/<session_id>/file.ext.

What changed

Concern v1 (deprecated) v2
Upload POST /v1/api/batch-inputs/upload — one file, referenced by UUID input_file_id POST /v1/api/files/upload — many files per session, integrity-checked with MD5
Discover files GET /v1/api/batch-inputs GET /v1/api/files with prefix / session / suffix filters
Create batch input_file_id + optional inputs, webhook_url input.files[] (avra:// paths), optional reference_date for backtesting
Result content_at URL on GET /v1/api/batches/{id}/result download_url + expires_at on GET /v2/api/batches/{id}/result

Webhooks are now configurable only through our notifications tool, via dashboard (see Webhooks). Input and Result deletions and Input downloads are no longer available in self-service ways to ensure security. Reach out to Avra if you need to remove a file.

Accepted file formats

Parquet is recommended for all inputs, and it’s the format results are written in (result.parquet). CSV is supported for low-complexity schemas. JSONL isn’t supported in v2. Migrate to Parquet.

Migration steps

Upload files into a session

Call POST /v1/api/files/upload with one target per file. Each target declares the destination file path, its content_type, and a base64-encoded md5 digest. You receive one signed upload_url per target and a session expiration.

{
  "targets": [
    { "file": "base/input1.csv", "content_type": "text/csv", "md5": "KPRxZBtAn5UfexFEKfKr7Q==" }
  ]
}

The response returns one entry per target, with these fields:

Field Description
file A reference for that file within Avra’s domain, avra://uploads/<session_id>/file.ext
content_type A MIME type for that file, matching the Content-Type provided in the request or, if not provided, inferred from the file extension
md5 The exact MD5 provided in the request, as a counter-proof to use
upload_url A signed, short-lived URL to upload the described file. It expects Content-Type and Content-MD5 headers matching the response values, and the storage rejects a mismatched digest
{
  "targets": [
      {
          "file": "avra://uploads/1784669990715/base/input1.csv",
          "content_type": "text/csv",
          "md5": "KPRxZBtAn5UfexFEKfKr7Q==",
          "upload_url": "https://storage.googleapis.com/..."
      }
  ],
  "expiration": "2026-07-21T22:39:50Z"
}

(Optional) List what you uploaded

Call GET /v1/api/files to enumerate uploaded files, optionally filtered by session, prefix, or suffix. Paths are returned in the avra:// scheme, ready to reference in a batch.

Create the batch

Call POST /v2/api/batches referencing the uploaded files. Provide model_id + model_version_id (or alias), an optional reference_date if backtesting, and the input definition.

{
  "model_id": "00000000-0000-0000-0000-000000000000",
  "model_version_id": "00000000-0000-0000-0000-000000000000",
  "reference_date": "2023-01-01",
  "input": { 
    "files": [
      "avra://uploads/1784143129686/base/input1.csv"
    ]
  }
}

Avra returns the batch id and status so you can track the job.

Poll and download

Poll GET /v2/api/batches/{id} for status. When complete, call GET /v2/api/batches/{id}/result to receive a signed download_url that expires at expires_at.

Was this page helpful?