Create a Batch

This endpoint facilitates the creation of a new batch within a project.

object

string

required

The name of the project this batch (and its tasks) belong to.

string

required

Name identifying this batch. Must be unique among all batches belonging to a customer.

string

The full url (including the scheme http:// or https://) or email address of the callback that will be used when the task is completed.

boolean

Only applicable for Rapid projects. Create an calibration batch by setting the calibration_batch flag to true.

boolean

Only applicable for Rapid projects. Create a self label batch by setting the self_label_batch flag to true.

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/batches"

# Define the payload for creating a new batch
payload = {
    "project": "kitten_labeling",       # The project associated with the batch
    "name": "kitten_labeling_2020-07",  # The name of the batch
    "calibration_batch": False,         # Indicates if the batch is a calibration batch
    "self_label_batch": False           # Indicates if the batch is a self-label batch
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the batch payload
batch_payload = {
    "project": "project_name",  # The name of the project this batch belongs to
    "name": "batch_name",  # The unique name for this batch
    "callback": "http://www.example.com/callback",  # The callback URL or email
    "calibration_batch": False,  # Only applicable for Rapid projects
    "self_label_batch": False  # Only applicable for Rapid projects
}

# Create the batch
batch = client.create_batch(**batch_payload)

# Print the created batch's details
print(batch.as_dict())

Finalize Batch

For “Scale Rapid and Studio” customers only, finalizes a batch with name batchName so its tasks can be worked on. Non-(Rapid/Studio) customers do not need to use this endpoint - calling this endpoint will not do anything, but still return a 200 success status code.

object

string

required

Required batchName to finalize.

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/batches/kitten_labeling_2020-07/finalize"

# Set up the headers for the request
headers = {
    "accept": "application/json"  # Specify that we want the response in JSON format
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the batch name to finalize
batch_name = "kitten_labeling_2020-07"

# Finalize the batch using the direct method
client.finalize_batch(batch_name=batch_name)

# Alternative method to finalize the batch
batch = client.get_batch(batch_name=batch_name)
batch.finalize()

# Print confirmation
print(f"Batch '{batch_name}' has been finalized.")

{
    "project": "TEST-PROJECT",
    "name": "BATCH-NAME",
    "callback": "your@email.com",
    "status": "in_progress",
    "created_at": "2023-08-01T23:04:12.168Z",
    "metadata": {}
}

Batch Retrieval

This endpoint returns the details of a batch with the name :batchName.

object

string

required

batchName to retrieve

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/batches/kitten_labeling_2020-07"

# Set up the headers for the request
headers = {
    "accept": "application/json"  # Specify that we want the response in JSON format
}

# Adding authentication to the GET request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.get(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the batch name to retrieve
batch_name = "kitten_labeling_2020-07"

# Retrieve the batch details
batch = client.get_batch(batch_name=batch_name)

# Print the batch details
print(batch.as_dict())

{
    "project": "PROJECT-NAME",
    "name": "BATCH_NAME",
    "callback": "your@email.com",
    "status": "in_progress",
    "created_at": "2023-05-16T19:02:23.149Z",
    "metadata": {}
}

Batch Status

This endpoint returns the status of a batch with the name :batchName, as well as the counts of its tasks grouped by task status.

object

string

required

Required batchName to get status.

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/batches/kitten_labeling_2020-07/status"

# Set up the headers for the request
headers = {
    "accept": "application/json"  # Specify that we want the response in JSON format
}

# Adding authentication to the GET request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.get(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define the batch name to retrieve the status
batch_name = "kitten_labeling_2020-07"

# Retrieve the batch status using the direct method
batch_status = client.batch_status(batch_name=batch_name)
print(batch_status)

# Alternative method to retrieve the batch status
batch = client.get_batch(batch_name=batch_name)
batch.get_status()  # Refreshes tasks_{status} attributes of Batch
print(f"Tasks Pending: {batch.tasks_pending}, Tasks Completed: {batch.tasks_completed}")

{
    "status": "in_progress",
    "tasks_pending": 9,
    "tasks_completed": 1
}

List All Batches

This is a paged endpoint for all of your batches. Batches will be returned in descending order based on created_at. Pagination is based off limit and offset parameters, which determine the page size and how many results to skip.

object

string

Project name to filter batches by.

string

Status to filter batches by (staging or in_progress or completed).

boolean

Get details about the progress of the batches.

string

The minimum value of created_at for batches to be returned

string

The maximum value of created_at for batches to be returned

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint with query parameters
url = "https://api.scale.com/v1/batches?project=kitten_labeling&status=in_progress&detailed=false&start_time=2020-05-21&end_time=2021-01-01&limit=100&offset=0"

# Set up the headers for the request
headers = {
    "accept": "application/json"  # Specify that we want the response in JSON format
}

# Adding authentication to the GET request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.get(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

import scaleapi

# Initialize the ScaleClient with your API key
client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

# Define optional filters
project_name = "project_name"  # Filter by project name (optional)
batch_status = "in_progress"  # Filter by status (optional)
exclude_archived = True  # Exclude archived batches (optional)
created_after = "2023-01-01T00:00:00Z"  # Filter by start time (optional)
created_before = "2023-12-31T23:59:59Z"  # Filter by end time (optional)

# Retrieve the list of all batches with optional filters
batches = client.get_batches(
    project_name=project_name,
    batch_status=batch_status,
    exclude_archived=exclude_archived,
    created_after=created_after,
    created_before=created_before
)

# Print the details of each batch
for batch in batches:
    print(batch.as_dict())

{  
   "completed_at": "2023-02-02T10:17:35.379Z",
    "created_at": "2023-02-02T10:17:35.379Z",
    "metadata": {},
    "name": "BATC_NAME",
    "project": "PROJECT_NAME",
    "status": "in_progress"
}

Batch Priorization

This endpoint updates the priority of a batch. The batch priority should follow the same parameters as an individual task’s priority, namely that priority should be between 10 for the lowest and 30 for the highest priority. Setting a task’s priority will impact the order in which the task is first picked up, but does not guarantee the order in which a task or set of tasks will be returned to you. As a result, tasks that are not yet started can be reprioritized, but tasks that are already started will not be impacted

object

string

required

The name of the batch to update.

object

string

required

The new priority for the batch. The priority should be between 10, representing the lowest priority, and 30, representing the highest priority.

import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/batches/kitten_labeling_2020-07/prioritize"

# Define the payload to update the batch priority
payload = {
    "priority": 10  # Set the priority level
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

{
  "result": "success"
}

Scale API

GenAI Data Engine

Automotive Data Engine

Automotive Data Engine Task Types

Batches

Create a Batch

Finalize Batch

Batch Retrieval

Batch Status

List All Batches

Batch Priorization

​Create a Batch

​Finalize Batch

​Batch Retrieval

​Batch Status

​List All Batches

​Batch Priorization

Create a Batch

Finalize Batch

Batch Retrieval

Batch Status

List All Batches

Batch Priorization