> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genai.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Batch Metadata

> Update the metadata for a [Batch](/core-resources/batch).

<Accordion title="Authentication" icon="key">
  Every request sent to Scale's API requires authentication. In short, your API Key is the Bearer token. See the [Authentication](/get-started/authentication) section for more details.
</Accordion>

<Tip>
  ### Required query parameters

  You are expected to provide one of the following:

  * **Batch ID** (`batch_id`)
  * **Batch Name** (`batch_name`)
</Tip>


## OpenAPI

````yaml POST /v2/batch/metadata
openapi: 3.1.0
info:
  title: GenAI API Spec
  description: 'Data Engine: Generative AI API Specification'
  version: 0.0.1
servers:
  - url: https://api.scale.com
security:
  - bearerAuth: []
  - basicAuth: []
paths:
  /v2/batch/metadata:
    post:
      tags:
        - v2
      summary: Set Batch Metadata
      description: Update the metadata for a [Batch](/core-resources/batch).
      operationId: setBatchMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - metadata
              properties:
                batch_id:
                  $ref: '#/components/schemas/BatchId'
                batch_name:
                  $ref: '#/components/schemas/BatchName'
                metadata:
                  $ref: '#/components/schemas/BatchMetadata'
                merge:
                  type: boolean
                  description: >-
                    Whether to deep merge the provided metadata with existing
                    metadata. If false, replaces the entire metadata object. If
                    true, performs a deep merge and replaces existing keys with
                    new values.
                  default: false
            examples:
              Using Batch ID:
                value:
                  batch_id: batch_123
                  metadata:
                    priority: high
                    dataset_version: v1.2
                    calibration_batch: true
              Using Batch Name:
                value:
                  batch_name: My Batch Name
                  metadata:
                    environment: production
                    model_version: '2.0'
      responses:
        '200':
          description: Batch metadata updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
              examples:
                Updated Batch:
                  $ref: '#/components/examples/SampleBatch'
        '500':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status_code:
                    type: number
                    example: 500
                  error:
                    type: string
                    example: An error has occurred.
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            API_KEY='live_...'
            BATCH_ID='batch_123'
            curl --request POST \
                --url "https://api.scale.com/v2/batch/metadata" \
                --header "Authorization: Bearer $API_KEY" \
                --header "Content-Type: application/json" \
                --data '{
                  "batch_id": "'$BATCH_ID'",
                  "metadata": {
                    "priority": "high",
                    "dataset_version": "v1.2"
                  }
                }'
        - lang: python
          label: Python SDK
          source: |
            import scaleapi

            API_KEY = 'live_...'
            client = scaleapi.ScaleClient(API_KEY)

            BATCH_ID = 'batch_123'
            response = client.v2.set_batch_metadata(
              batch_id=BATCH_ID,
              metadata={
                "priority": "high",
                "dataset_version": "v1.2"
              }
            )
            print(response.to_json())
        - lang: python
          label: Python
          source: |
            import requests

            API_KEY = 'live_...'
            BATCH_ID = 'batch_123'

            response = requests.request(
              "POST",
              url="https://api.scale.com/v2/batch/metadata",
              json={
                "batch_id": BATCH_ID,
                "metadata": {
                  "priority": "high",
                  "dataset_version": "v1.2"
                }
              },
              headers={
                "Accept": "application/json",
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json",
              },
            )
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >
            const API_KEY = 'live_...';

            const BATCH_ID = 'batch_123';


            const response = await
            fetch('https://api.scale.com/v2/batch/metadata', {
              method: 'POST',
              headers: {
                Accept: 'application/json',
                Authorization: `Bearer ${API_KEY}`,
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({
                batch_id: BATCH_ID,
                metadata: {
                  priority: 'high',
                  dataset_version: 'v1.2'
                }
              }),
            });

            console.log(await response.json());
        - lang: go
          label: Go
          source: |
            package main

            import (
              "bytes"
              "encoding/json"
              "fmt"
              "io/ioutil"
              "net/http"
            )

            func main() {
              apiKey := "live_..."
              batchId := "batch_123"

              requestBody := map[string]interface{}{
                "batch_id": batchId,
                "metadata": map[string]interface{}{
                  "priority": "high",
                  "dataset_version": "v1.2",
                },
              }
              jsonData, _ := json.Marshal(requestBody)

              req, _ := http.NewRequest("POST", "https://api.scale.com/v2/batch/metadata", bytes.NewBuffer(jsonData))

              req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey))
              req.Header.Add("Content-Type", "application/json")

              res, _ := http.DefaultClient.Do(req)

              defer res.Body.Close()
              body, _ := ioutil.ReadAll(res.Body)

              fmt.Println(string(body))
            }
        - lang: java
          label: Java
          source: |
            package com.scale.api;

            import kong.unirest.HttpResponse;
            import kong.unirest.Unirest;

            public class App {
                public static void main(String[] args) {
                    String apiKey = "live_...";
                    String batchId = "batch_123";

                    String requestBody = String.format(
                      "{\"batch_id\": \"%s\", \"metadata\": {\"priority\": \"high\", \"dataset_version\": \"v1.2\"}}", 
                      batchId
                    );

                    HttpResponse<String> response = Unirest.post("https://api.scale.com/v2/batch/metadata")
                      .header("Authorization", String.format("Bearer %s", apiKey))
                      .header("Content-Type", "application/json")
                      .body(requestBody)
                      .asString();

                    System.out.println(response.getBody());
                }
            }
components:
  schemas:
    BatchId:
      type: string
      description: A unique identifier for the batch.
      example: batch_abc123
    BatchName:
      type: string
      description: The name of the batch.
      example: My Scale Batch
    BatchMetadata:
      $ref: '#/components/schemas/Metadata'
    Batch:
      type: object
      required:
        - id
        - name
        - project
        - created_at
        - status
        - metadata
      properties:
        id:
          $ref: '#/components/schemas/BatchId'
        name:
          $ref: '#/components/schemas/BatchName'
        project:
          $ref: '#/components/schemas/ExpandableProject'
          description: >-
            Project ID or [Project](/core-resources/project) associated with the
            batch.
        created_at:
          $ref: '#/components/schemas/DateString'
        completed_at:
          $ref: '#/components/schemas/DateString'
          description: UTC timestamp when the batch was completed.
        status:
          $ref: '#/components/schemas/BatchStatus'
        callback:
          $ref: '#/components/schemas/Callback'
        metadata:
          $ref: '#/components/schemas/BatchMetadata'
    Metadata:
      type: object
      description: Custom metadata for the entity.
      additionalProperties: true
      default: {}
    ExpandableProject:
      description: >-
        Project ID or [Project](/core-resources/project) associated with the
        task.
      oneOf:
        - $ref: '#/components/schemas/ProjectId'
        - $ref: '#/components/schemas/Project'
    DateString:
      type: string
      format: date-time
      description: A timestamp formatted as an ISO 8601 date-time string.
    BatchStatus:
      type: string
      enum:
        - staging
        - in_progress
        - completed
        - paused
        - cancelled
      description: Status of the batch.
    Callback:
      type: string
      description: Callback URL or email for the entity upon completion.
      example: https://example.com/callback
    ProjectId:
      type: string
      description: A unique identifier for the project.
      example: project_abc123
    Project:
      type: object
      required:
        - id
        - name
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/ProjectId'
          description: Unique identifier for the project
        name:
          $ref: '#/components/schemas/ProjectName'
        created_at:
          $ref: '#/components/schemas/DateString'
        types:
          type: array
          description: List of project types associated with the project.
          items:
            $ref: '#/components/schemas/GenAIProjectType'
          example:
            - 'RLHF: Pref Ranking'
        models:
          type: array
          description: List of models associated with the project.
          items:
            $ref: '#/components/schemas/Model'
          example:
            - gpt-4
            - my-model-123
    ProjectName:
      type: string
      description: The name of the project.
      example: My Scale Project
    GenAIProjectType:
      type: string
      enum:
        - SFT
        - 'RLHF: Pref Ranking'
        - 'RLHF: Pref Ranking with Rewrites'
        - 'RLVR: Reinforcement Learning with Verifiable Rewards'
        - Rubrics
        - Process Supervision
        - Evals
        - Prompt Generation
        - Content Understanding
        - Other
    Model:
      type: string
      description: The name of the model that generated the message.
      example: my-model-123
  examples:
    SampleBatch:
      value:
        id: batch_123
        name: Batch Name Example
        project: project_123
        created_at: '2022-07-25T07:32:34.318Z'
        status: completed
        callback: https://example.com/callback
        metadata: {}
        completed_at: '2022-07-26T07:32:34.318Z'
  securitySchemes:
    bearerAuth:
      description: >-
        Your API Key is the Bearer token. See the
        [Authentication](/get-started/authentication) section to learn how to
        access your key.
      type: http
      scheme: bearer
    basicAuth:
      description: >-
        Basic HTTP Authentication. Your API Key is your username.  Learn more
        about setting up Authentication [here](/get-started/authentication).
      type: http
      scheme: basic

````