Create a Batch

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

Body Params

projectstringrequired

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

namestringrequired

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

callbackstring

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

calibration_batchboolean

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

self_label_batchboolean

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

Request

POST/v1/projects
import requests
url = "https://api.scale.com/v1/projects"

payload = {
    "type": "imageannotation",
    "name": "project_name",
    "rapid": False,
    "studio": True,
    "params": { "instruction": "Instructions" },
    "pipeline": "pipelinen_name"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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.

Body Params

batchNamestringrequired

Required batchName to finalize.

Request

POST/v1/batches/{batchName}/finalize
import requests

url = "https://api.scale.com/v1/batches/kitten_labeling_2020-07/finalize"

headers = {
    "accept": "application/json",
    "authorization": "Basic c2NhbGVpbnRfZWMyMjU0MWQ2OWE1NDBlYWE0OTgyNWNlNjM2ODNiNDV8NjM0NzMwZDkwZTI2NDMwMDMxNTM0ZjFjOg=="
}

response = requests.post(url, headers=headers)

print(response.text)

Response

{
    "project": "TEST-PROJECT",
    "name": "BATCH-NAME",
    "callback": "[email protected]",
    "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.

Path Params

batchNamestringrequired

batchName to retrieve

Request

GET/v1/batches/{batchName}
import requests

url = "https://api.scale.com/v1/batches/kitten_labeling_2020-07"

headers = {
    "accept": "application/json",
    "authorization": "Basic c2NhbGVpbnRfZWMyMjU0MWQ2OWE1NDBlYWE0OTgyNWNlNjM2ODNiNDV8NjM0NzMwZDkwZTI2NDMwMDMxNTM0ZjFjOg=="
}

response = requests.get(url, headers=headers)

print(response.text)

Response

{
    "project": "PROJECT-NAME",
    "name": "BATCH_NAME",
    "callback": "[email protected]",
    "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.

Path Params

batchNamestringrequired

Required batchName to get status.

Request

GET/v1/batches/{batchName}/status
import requests

url = "https://api.scale.com/v1/batches/kitten_labeling_2020-07/status"

headers = {
    "accept": "application/json",
    "authorization": "Basic c2NhbGVpbnRfZWMyMjU0MWQ2OWE1NDBlYWE0OTgyNWNlNjM2ODNiNDV8NjM0NzMwZDkwZTI2NDMwMDMxNTM0ZjFjOg=="
}

response = requests.get(url, headers=headers)

print(response.text)
GET/v1/batches/{batchName}/status
import scaleapi
import json

client = scaleapi.ScaleClient("YOUR-API-KE")
batch_name = "BATCH_NAME"

# Get batch
batch = client.get_batch(batch_name=batch_name)

# Get status
batch_status = batch.get_status()

# Create a dictionary to hold the batch details
batch_details = {
    "status": batch.status,
    "tasks_pending": batch.tasks_pending,
    "tasks_completed": batch.tasks_completed
}

# Convert the dictionary to a JSON string
batch_details_json = json.dumps(batch_details, indent=4)

# Print the JSON string
print(batch_details_json)

Response

{
    "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.

Query Params

projectstring

Project name to filter batches by.

statusstring

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

detailedboolean

Get details about the progress of the batches.

start_timestring

The minimum value of created_at for batches to be returned

end_timestring

The maximum value of created_at for batches to be returned

Request

GET/v1/batches
import requests

url = "https://api.scale.com/v1/batches"

headers = {
    "accept": "application/json",
    "authorization": "Basic c2NhbGVpbnRfZWMyMjU0MWQ2OWE1NDBlYWE0OTgyNWNlNjM2ODNiNDV8NjM0NzMwZDkwZTI2NDMwMDMxNTM0ZjFjOg=="
}

response = requests.get(url, headers=headers)

print(response.text)
GET/v1/batches
import scaleapi
from scaleapi import BatchStatus
import pprint

client = scaleapi.ScaleClient("YOUR-API-KEY")

# define your filters
project_name = "PROJECT-NAME"  # replace with your project name
batch_status = BatchStatus.InProgress  # replace with the batch status you want
created_after = "2023-01-01"  # replace with your desired date
created_before = "2023-12-31"  # replace with your desired date

# get the batches
batches = client.get_batches(
    project_name=project_name,
    batch_status=batch_status,
    created_after=created_after,
    created_before=created_before,
)

# pretty print the batches
pp = pprint.PrettyPrinter(indent=4)
for batch in batches:
    pp.pprint(batch.as_dict())

Response

{  
   "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

Path Params

batchNamestringrequired

The name of the batch to update.

Body Params

batchNamestringrequired

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

Request

POST/v1/batches/{batchName}/prioritize
import requests

url = "https://api.scale.com/v1/batches/BATCH_NAME/prioritize"

payload = { "priority": 1 }
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Basic c2NhbGVpbnRfZWMyMjU0MWQ2OWE1NDBlYWE0OTgyNWNlNjM2ODNiNDV8NjM0NzMwZDkwZTI2NDMwMDMxNTM0ZjFjOg=="
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response

{
  "result": "success"
}
Updated 5 days ago