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

# Batches

> Create a Batch Finalize Batch Batch Retrieval Batch Status List All Batches Batch Priorization

# Create a Batch

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

<ParamField path="Body Params" type="object">
  <ParamField path="project" type="string" required>
    The name of the project this batch (and its tasks) belong to.

    ***
  </ParamField>

  <ParamField path="name" type="string" required>
    Name identifying this batch. Must be unique among all batches belonging to a customer.

    ***
  </ParamField>

  <ParamField path="callback" type="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.

    ***
  </ParamField>

  <ParamField path="calibration_batch" type="boolean">
    Only applicable for Rapid projects. Create an calibration batch by setting the calibration\_batch flag to true.

    ***
  </ParamField>

  <ParamField path="self_label_batch" type="boolean">
    Only applicable for Rapid projects. Create a self label batch by setting the self\_label\_batch flag to true.

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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())

  ```
</CodeGroup>

<CodeGroup />

# 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.

<ParamField path="Body Params" type="object">
  <ParamField path="batchName" type="string" required>
    Required batchName to finalize.

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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.")

  ```
</CodeGroup>

```json theme={null}
{
    "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.

<ParamField path="Path Params" type="object">
  <ParamField path="batchName" type="string" required>
    batchName to retrieve

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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())

  ```
</CodeGroup>

```json theme={null}
{
    "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.

<ParamField path="Path Params" type="object">
  <ParamField path="batchName" type="string" required>
    Required batchName to get status.

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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}")

  ```
</CodeGroup>

```json theme={null}
{
    "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.

<ParamField path="Query Params" type="object">
  <ParamField path="project" type="string">
    Project name to filter batches by.

    ***
  </ParamField>

  <ParamField path="status" type="string">
    Status to filter batches by (staging or in\_progress or completed).

    ***
  </ParamField>

  <ParamField path="detailed" type="boolean">
    Get details about the progress of the batches.

    ***
  </ParamField>

  <ParamField path="start_time" type="string">
    The minimum value of created\_at for batches to be returned

    ***
  </ParamField>

  <ParamField path="end_time" type="string">
    The maximum value of created\_at for batches to be returned

    ***
  </ParamField>
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)

  ```

  ```python Python SDK theme={null}
  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())

  ```
</CodeGroup>

```json theme={null}
{  
   "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

<ParamField path="Path Params" type="object">
  <ParamField path="batchName" type="string" required>
    The name of the batch to update.

    ***
  </ParamField>
</ParamField>

<ParamField path="Body Params" type="object">
  <ParamField path="batchName" type="string" required>
    The new priority for the batch. The priority should be between 10, representing the lowest priority, and 30, representing the highest priority.

    ***
  </ParamField>
</ParamField>

```python theme={null}
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)

```

```json theme={null}
{
  "result": "success"
}
```