> ## 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.
# Get Multiple Batches
> Retrieve multiple [Batches](/core-resources/batch) from a [Project](/core-resources/project).
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.
## OpenAPI
````yaml GET /v2/batches
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/batches:
get:
tags:
- v2
summary: Get Multiple Batches
description: >-
Retrieve multiple [Batches](/core-resources/batch) from a
[Project](/core-resources/project).
operationId: getBatches
parameters:
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/project_name'
- $ref: '#/components/parameters/batch_status'
- $ref: '#/components/parameters/created_after'
- $ref: '#/components/parameters/created_before'
- $ref: '#/components/parameters/completed_after'
- $ref: '#/components/parameters/completed_before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/next_token'
- $ref: '#/components/parameters/expand_batch'
responses:
'200':
description: List of batches.
content:
application/json:
schema:
$ref: '#/components/schemas/GetBatchesResponse'
examples:
Sample Batches:
value:
batches:
- $ref: '#/components/examples/SampleBatch/value'
next_token: imatoken123
'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_...'
PARAMS='project_name=My+Test+Project&status=completed&limit=10'
curl --request GET \
--url "https://api.scale.com/v2/batches?$PARAMS" \
--header "Authorization: Bearer $API_KEY"
- lang: python
label: Python SDK
source: |
import scaleapi
API_KEY = 'live_...'
client = scaleapi.ScaleClient(API_KEY)
response = client.v2.get_batches(
project_name="My Test Project",
status="completed",
limit=10,
)
print(response.to_json())
- lang: python
label: Python
source: |
import requests
API_KEY = 'live_...'
params = {
"project_name": "My Test Project",
"status": "completed",
"limit": "10",
}
response = requests.request(
"GET",
url="https://api.scale.com/v2/batches",
params=params,
headers={
"Accept": "application/json",
"Authorization": f"Bearer {API_KEY}",
},
)
print(response.json())
- lang: javascript
label: JavaScript
source: >
const API_KEY = 'live_...';
const params = new URLSearchParams({
project_name: 'My Test Project',
status: 'completed',
limit: '10',
});
const response = await fetch('https://api.scale.com/v2/batches?' +
params.toString(), {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: `Bearer ${API_KEY}`,
},
});
console.log(await response.json());
- lang: go
label: Go
source: |
package main
import (
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
func main() {
apiKey := "live_..."
params := map[string]string{
"project_name": "My Test Project",
"status": "completed",
"limit": "10",
}
url := fmt.Sprintf("https://api.scale.com/v2/batches?%s", encodeQueryParams(params))
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
func encodeQueryParams(params map[string]string) string {
query := url.Values{}
for key, value := range params {
query.Add(key, value)
}
return query.Encode()
}
- lang: java
label: Java
source: |
package com.scale.api;
import kong.unirest.HttpResponse;
import kong.unirest.Unirest;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.Map;
import java.util.stream.Collectors;
public class App {
public static void main(String[] args) {
String apiKey = "live_...";
Map params = Map.of(
"project_name", "My Test Project",
"status", "completed",
"limit", "10"
);
String url = String.format("https://api.scale.com/v2/batches?%s", encodeQueryParams(params));
HttpResponse response = Unirest.get(url)
.header("Authorization", String.format("Bearer %s", apiKey))
.asString();
System.out.println(response.getBody());
}
private static String encodeQueryParams(Map params) {
return params.entrySet()
.stream()
.map(entry -> {
return String.format("%s=%s", utf8Encode(entry.getKey()), utf8Encode(entry.getValue()));
})
.collect(Collectors.joining("&"));
}
private static String utf8Encode(String s) {
try {
return URLEncoder.encode(s, "UTF-8");
} catch (UnsupportedEncodingException e) {
throw new RuntimeException("Error encoding string", e);
}
}
}
components:
parameters:
project_id:
name: project_id
in: query
required: false
description: Scale's unique identifier for the project.
schema:
$ref: '#/components/schemas/ProjectId'
project_name:
name: project_name
in: query
required: false
description: The name of the project.
schema:
$ref: '#/components/schemas/ProjectName'
batch_status:
name: status
in: query
required: false
description: >-
The current status of the batch, indicating whether it is staging,
in_progress, completed, or paused.
schema:
$ref: '#/components/schemas/BatchStatus'
created_after:
name: created_after
in: query
required: false
description: >-
Projects with a `created_at` after the given date will be returned. A
timestamp formatted as an ISO 8601 date-time string.
schema:
$ref: '#/components/schemas/DateString'
created_before:
name: created_before
in: query
required: false
description: >-
Projects with a `created_at` before the given date will be returned. A
timestamp formatted as an ISO 8601 date-time string.
schema:
$ref: '#/components/schemas/DateString'
completed_after:
name: completed_after
in: query
required: false
description: >-
Tasks with a `completed_at` after the given date will be returned. A
timestamp formatted as an ISO 8601 date-time string.
schema:
$ref: '#/components/schemas/DateString'
completed_before:
name: completed_before
in: query
required: false
description: >-
Tasks with a `completed_at` before the given date will be returned. A
timestamp formatted as an ISO 8601 date-time string.
schema:
$ref: '#/components/schemas/DateString'
limit:
name: limit
in: query
required: false
description: Limit the number of entities returned.
schema:
$ref: '#/components/schemas/Limit'
next_token:
name: next_token
in: query
required: false
description: >-
A token used to retrieve the next page of results if there are more. You
can find the `next_token` in your last request.
schema:
$ref: '#/components/schemas/NextToken'
expand_batch:
name: expand
in: query
required: false
description: >-
List of fields to [expand](/api-reference/expanding-entities) in the
response.
schema:
$ref: '#/components/schemas/ExpandBatch'
schemas:
GetBatchesResponse:
type: object
required:
- batches
properties:
batches:
$ref: '#/components/schemas/Batches'
next_token:
$ref: '#/components/schemas/NextToken'
ProjectId:
type: string
description: A unique identifier for the project.
example: project_abc123
ProjectName:
type: string
description: The name of the project.
example: My Scale Project
BatchStatus:
type: string
enum:
- staging
- in_progress
- completed
- paused
- cancelled
description: Status of the batch.
DateString:
type: string
format: date-time
description: A timestamp formatted as an ISO 8601 date-time string.
Limit:
type: integer
minimum: 1
maximum: 100
NextToken:
type: string
description: >-
A token used to retrieve the next page of results if there are more. You
can find the `next_token` in your last request
ExpandBatch:
type: array
description: >-
Entities that can be [expanded](/api-reference/expanding-entities) from
an ID to an object.
items:
$ref: '#/components/schemas/ExpandableEnumBatch'
Batches:
type: array
description: Array of batch objects
items:
$ref: '#/components/schemas/Batch'
ExpandableEnumBatch:
type: string
description: Entities that can be expanded from an ID to an object.
enum:
- project
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'
Callback:
type: string
description: Callback URL or email for the entity upon completion.
example: https://example.com/callback
BatchMetadata:
$ref: '#/components/schemas/Metadata'
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: {}
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
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
````