> ## 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.
# Finalize a Batch
> Move a [Batch](/core-resources/batch) from staging to in-progress status to begin processing tasks.
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.
### Batch Status Requirement
You can only finalize batches that are currently in **staging** status. Batches in other statuses (in\_progress, completed, paused) cannot be finalized.
Once finalized, the batch status will change to **in\_progress** and task processing will begin.
### Required request parameters
You are expected to provide one of the following in the request body:
* **Batch ID** (`batch_id`)
* **Batch Name** (`batch_name`)
## OpenAPI
````yaml POST /v2/batch/finalize
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/finalize:
post:
tags:
- v2
summary: Finalize a Batch
description: >-
Move a [Batch](/core-resources/batch) from staging to in-progress status
to begin processing tasks.
operationId: finalizeBatch
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchOperationRequest'
examples:
Using Batch ID:
value:
batch_id: batch_123
Using Batch Name:
value:
batch_name: My Batch Name
responses:
'200':
description: Batch finalized successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
examples:
Finalized 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/finalize" \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{"batch_id": "'$BATCH_ID'"}'
- lang: python
label: Python SDK
source: |
import scaleapi
API_KEY = 'live_...'
client = scaleapi.ScaleClient(API_KEY)
BATCH_ID = 'batch_123'
response = client.v2.finalize_batch(BATCH_ID)
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/finalize",
json={"batch_id": BATCH_ID},
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/finalize', {
method: 'POST',
headers: {
Accept: 'application/json',
Authorization: `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ batch_id: BATCH_ID }),
});
console.log(await response.json());
components:
schemas:
BatchOperationRequest:
type: object
description: Request object for batch operations (finalize, pause, resume, cancel)
properties:
batch_id:
$ref: '#/components/schemas/BatchId'
batch_name:
$ref: '#/components/schemas/BatchName'
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'
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
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
BatchMetadata:
$ref: '#/components/schemas/Metadata'
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
Metadata:
type: object
description: Custom metadata for the entity.
additionalProperties: true
default: {}
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
````