---
title: "Replace a batch's metadata"
method: POST
path: "/v1/batches/{id}/metadata"
tags: ["Batches"]
---

# Replace a batch's metadata

`POST /v1/batches/{id}/metadata`

Replace the batch's metadata map with the one you send; the whole map is overwritten, so include every pair you want to keep and send an empty object to clear it. Metadata is opaque customer data, not lifecycle state, so it is editable at any time including after the batch is terminal. Returns the updated batch.

## Path parameters

- `id` string, required

## Request body

- object
  - `metadata` object, required — At most 32 pairs; each key is 1-64 characters and each value is at most 512 characters (counted in Unicode code points). An empty object clears all metadata.

## Response `200`

OK

- BatchObject — A batch inference job (OpenAI-compatible).
  - `cancelled_at` integer
  - `completed_at` integer
  - `completion_window` '24h', required
  - `created_at` integer, required — Unix timestamp (seconds).
  - `endpoint` string, required — The API family every record in the batch calls.
  - `error_file_id` string — Present once results are written; fetch its content for failed records.
  - `expired_at` integer
  - `expires_at` integer — When the completion window closes (created_at + 24h).
  - `failed_at` integer
  - `id` string, required — Batch id (batch_…).
  - `input_file_id` string, required
  - `metadata` object — Your key-value pairs, echoed back unchanged.
  - `model` string — Model id, settled from the input file during validation.
  - `object` 'batch', required
  - `output_file_id` string — Present once results are written; fetch its content for successful records.
  - `priority` 'standard' | 'expedited', required — The scheduling tier this batch runs and is billed at. Batches created before the tier existed read as standard.
  - `request_counts` BatchRequestCounts, required — Progress counters, settled as the batch validates and shards complete.
    - `completed` integer, required
    - `failed` integer, required
    - `total` integer, required
  - `status` 'validating' | 'in_progress' | 'finalizing' | 'completed' | 'failed' | 'expired' | 'cancelling' | 'cancelled', required — Lifecycle state. validating → in_progress → finalizing → completed | failed | expired; cancelling → cancelled.
  - `usage` BatchUsage — Rolled-up token and cost totals, present once any progress is recorded. cost_nano_usd is the price you pay (batch discount applied), in nano-USD so sub-cent batches stay exact.
    - `cost_nano_usd` integer, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required

## Other responses

- `400` — The request is invalid
- `401` — Missing or invalid API key
- `404` — Not found (also returned when the organization does not have Batch API access)
- `413` — The upload exceeds the 200 MB limit

## Changes

- **2026-09-19** `702f7cdaf46f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrelay/apis/openrelay-api/changes/v1/batches/:id/metadata/post.md)

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/b684124c1a8d?raw)