### Install Scale API Javascript library

Source: https://scale.com/docs/api-reference/introduction-to-scale-api

Install the Scale API client for Javascript using npm.

```shell
$   npm install scaleapi --save
```

--------------------------------

### Install Scale API Python library

Source: https://scale.com/docs/api-reference/introduction-to-scale-api

Install the Scale API client for Python using pip or conda.

```shell
pip install --upgrade scaleapi

conda install -c conda-forge scaleapi # If using Anaconda package management
```

--------------------------------

### Batch Object JSON Example

Source: https://scale.com/docs/api-reference/data-engine-reference

Example of a batch object in JSON format, showing fields such as project, name, status, callback, and created_at. This example is referenced in the workflow steps for Enterprise, Rapid, and Studio.

```json
{
  "project": "kitten_labeling",
  "name": "kitten_labeling_2020-07",
  "status": "staging",
  "callback": "https://example.com/callback",
  "created_at": "2020-07-01T09:09:10.108Z"
}
```

--------------------------------

### Retrieve a task using HTTP requests or Python SDK

Source: https://scale.com/docs/api-reference/tasks

Two Python examples for retrieving a task from the Scale API. The first uses the requests library with an HTTP GET request to the endpoint, requiring an API key for authentication. The second uses the Scale Python SDK, initializing a ScaleClient and calling get_task with a task ID.

```python
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/task/576ba74eec471ff9b01557cc"

# 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
import scaleapi

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

# Define the task ID to retrieve
task_id = "601ba74eec471ff9b01557cc"  # Replace with your actual task ID

# Retrieve the task details
task = client.get_task(task_id)

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

```

--------------------------------

### Image Annotation Taxonomy and param_chunks Example

Source: https://scale.com/docs/rapid-or-taxonomy-chunking

Example taxonomy for image annotation with geometries, annotation attributes, and links. The param_chunks example shows how to group labels for annotation tasks.

```javascript
geometries: {
  box: {
    objects_to_annotate: [
      'plastic_bag',
      'vegetable',
      { choice: 'fruit', subchoices: ['apple', 'banana'] },
    ],
    min_width: 0,
    min_height: 0,
    examples: [],
  },
  polygon: {
    objects_to_annotate: ['camera'],
  },
},
annotation_attributes: {
  color: {
    choices: ['green', 'white', 'yellow'],
    description: 'color',
  },
  glare: {
    description: 'Is there glare on the image?',
    choices: ['sun glare', 'night headlight glare', 'none'],
    conditions: {
      is_global: true,
    },
  },
},
links: {
  'Camera Sees': [
    {
      is_bidirectional: false,
      from_allowed_labels: ['camera'],
      to_allowed_labels: ['vegetable', 'apple', 'banana'],
    },
  ],
  Contains: [
    {
      is_bidirectional: false,
      from_allowed_labels: ['plastic_bag'],
      to_allowed_labels: ['vegetable', 'apple', 'banana'],
    },
  ],
}

```

```javascript
param_chunks: [
  ['plastic_bag', 'fruit', 'glare'],
  ['vegetable', 'camera'],
]

```

--------------------------------

### Project JSON Structure

Source: https://scale.com/docs/api-reference/projects

Example of the JSON object structure returned for a project.

```json
{
  "type": "imageannotation",
  "name": "project_name",
  "param_history": [
    {
      "instruction": "Instructions",
      "version": 0,
      "created_at": "2021-04-25T07:38:32.368Z"
    }
  ],
  "created_at": "2021-04-25T07:38:32.368Z"
}
```

--------------------------------

### Create a project using the Scale Python SDK

Source: https://scale.com/docs/api-reference/projects

This example shows how to initialize the ScaleClient and use the create_project method to programmatically create a project.

```python
import scaleapi
from scaleapi.tasks import TaskType

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

# Define the project payload
project_payload = {
    "type": TaskType.ImageAnnotation,
    "name": "project_name",
    "rapid": False,  # Set to True if creating a Scale Rapid project
    "studio": True,  # Set to True if creating a Scale Studio project
    "params": {
        "instruction": "Instructions"
    },
    "pipeline": "pipeline_name"  # Specify the pipeline name for Studio projects
}

# Create the project
project = client.create_project(**project_payload)

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

--------------------------------

### Create a project using the requests library

Source: https://scale.com/docs/api-reference/projects

This example demonstrates how to create a new project by sending a POST request to the Scale API endpoint using the Python requests library.

```python
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/projects"

# Define the payload for creating a new project
payload = {
    "type": "imageannotation",  # Type of the project
    "name": "kitten_labeling",  # Name of the project
    "rapid": False,             # Indicates if the project is a rapid project
    "studio": False,            # Indicates if the project uses Scale AI's Studio interface
    "params": { 
        "instruction": "Please label the kittens"  # Instructions for the annotation task
    }
}

# 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)
```

--------------------------------

### Task object example - JSON

Source: https://scale.com/docs/api-reference/data-engine-reference

Full example of a completed task object from the Scale API. Shows the structure for fields like task_id, status, params, response, audits, and metadata.

```json
{
  "task_id": "576ba74eec471ff9b01557cc",
  "created_at": "2016-06-23T09:09:34.752Z",
  "updated_at": "2016-06-23T09:10:02.798Z",
  "completed_at": "2016-06-23T09:10:02.798Z",  
  "type": "categorization",
  "status": "completed",
  "instruction": "Would you say this item is big or small?",
  "params": {
    "attachment_type": "text",
    "attachment": "car",
    "categories": [
      "big",
      "small"
    ]
  },
  "callback_url": "http://www.example.com/callback",
  "callback_completed": true,
  "response": {
    "category": "big"
  },
  "metadata": {},
  "audits": [
    {
      "audited_by": "david@company.com",
      "audited_at": "2016-06-23T10:01:02.352Z",
      "audit_time_secs": 120,
      "audit_result": "accepted",
      "audit_source": "customer"
    },
    {
      "audited_by": "auditor@scale.com",
      "audited_at": "2016-06-23T10:01:02.352Z",
      "audit_time_secs": 511,
      "audit_result": "fixed",
      "audit_source": "scale"
    }
  ],
  "tags": ["experiment_1", "owner:david"],
  "unique_id": "product_experiment_dg3d9x83"
}
```

--------------------------------

### Project parameter history JSON structure

Source: https://scale.com/docs/api-reference/projects

Example of the JSON structure returned for a project, including the param_history field.

```json
{
   "type": "imageannotation",
   "name": "kitten_labeling",
   "param_history": [
       {
       "instruction": "please label the kittens in the image",
       "version": 0,
       "created_at": "2021-04-25T07:38:32.368Z"
       }
    ],
   "created_at": "2021-04-25T07:38:32.368Z"
}
```

--------------------------------

### Categorical attribute response examples

Source: https://scale.com/docs/api-reference/annotation-attributes

Response examples for categorical attributes. When allow_multiple is false, the response is a single string; when true, it is an array of strings.

```json
{
  "example_attribute": "Answer1"
}
```

```json
{
  "example_attribute": [
    "Answer1",
    "Answer2"
  ]
}
```

--------------------------------

### Line annotation request example

Source: https://scale.com/docs/api-reference/image-and-video-reference

Example request body for creating line annotations. The objects_to_annotate array can contain strings or LabelDescription objects, and min_vertices and max_vertices define the allowed number of vertices.

```json
{
  "geometries": {
    "line": {
      "objects_to_annotate": [
        "unmarked_lane",
        {
          "choice": "marked lanes",
          "subchoices": [
            "solid",
            {
              "choice": "dashed",
              "display": "dashed or dotted"
            }
          ]
        },
        "shoulder"
      ],
      "min_vertices": 2,
      "max_vertices": 15
    },
    ...
  },
  ...
}
```

--------------------------------

### Set task metadata with requests and Scale Python SDK

Source: https://scale.com/docs/api-reference/tasks

Two Python examples for setting task metadata: one using the raw HTTP API with requests, and one using the Scale Python SDK. Both require an API key and a valid task ID. The raw example posts to the /v1/task/{taskId}/setMetadata endpoint; the SDK example calls client.set_task_metadata(task_id, metadata).

```python
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/task/576ba74eec471ff9b01557cc/setMetadata"

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

# Define the payload for setting metadata
payload = {
    # Add your metadata here
    # For example: "metadata_key": "metadata_value"
}

# 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, json=payload, auth=(API_KEY, ''))

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

```

```python
import scaleapi

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

# Define the task ID and the metadata to set
task_id = "601ba74eec471ff9b01557cc"  # Replace with your actual task ID
metadata = {
    "key1": "value1",
    "key2": "value2"
}

# Set the metadata for the task
client.set_task_metadata(task_id, metadata)

# Print confirmation
print(f"Metadata for task '{task_id}' has been set to {metadata}.")

```

--------------------------------

### Example task response JSON

Source: https://scale.com/docs/api-reference/tasks

Example JSON response for a task retrieval, showing the task object with fields such as task_id, created_at, callback_url, type, status, instruction, params, and metadata. The status is 'canceled' and the type is 'imageannotation'.

```json
{
  "task_id": "601ba74eec471ff9b01557cc",
  "created_at": "2021-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "imageannotation",
  "status": "canceled",
  "instruction": "Label every object in this image",
  "params": {
    "attachment": "https://example.com/image.jpg",
    "geometries": {
      "box": {
        "objects_to_annotate": [
          "vehicle",
          "pedestrian"
        ]
      }
    }
  },
  "metadata": {
    "key": "value",
    "key2": "value2"
  }
}

```

--------------------------------

### Multi-Stage Task Response Example

Source: https://scale.com/docs/api-reference/create-multi-stage-task

Sample JSON response returned by the API after creating a multi-stage task. Shows the task ID, status, and other metadata.

```json
{
  "callback_url": "http://www.example.com/callback",
  "created_at": "2024-01-16T21:03:33.166Z",
  "instruction": "Annotate the *vehicles* and *pedestrians* in the scene.",
  "is_test": false,
  "params": {},
  "status": "pending",
  "task_id": "5a99e20de50d4979ce6d291e",
  "type": "multistage"
}
```

--------------------------------

### Ellipse annotation response example

Source: https://scale.com/docs/api-reference/image-and-video-reference

JSON example showing the response for an ellipse annotation, including vertices, label, attributes, and uuid.

```json
{
  "response": {
    "annotations": [
      {
        "type": "ellipse",
        "label": "wheel",
        "attributes": {
            "position": "front_left"
        },
        "vertices": [
            {
                "x": 123,
                "y": 92
            },
            {
                "x": 173,
                "y": 113
            },
            {
                "x": 123,
                "y": 134
            },
            {
                "x": 73,
                "y": 113
            }
        ],
        "uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
      },
      { ... },
      { ... }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // task inlined for convenience
    ...
  }
}
```

--------------------------------

### Example JSON response for project retrieval

Source: https://scale.com/docs/api-reference/projects

Sample JSON response from the project retrieval endpoint, showing project fields such as type, name, parameter history, and creation timestamp.

```json
{
   "type": "imageannotation",
   "name": "kitten_labeling",
   "param_history": [
       {
       "instruction": "Instructions",
       "version": 0,
       "created_at": "2021-04-25T07:38:32.368Z"
       }
   ],
   "created_at": "2021-04-25T07:38:32.368Z"
}
```

--------------------------------

### Example project response structure

Source: https://scale.com/docs/api-reference/projects

This JSON object represents the structure of a project response returned by the API.

```json
{
"type": "imageannotation",
"pipelineName": "pipeline_name",
"numReviews": 0,
"numConsensus": 0,
"created_at": "2023-08-04T15:11:57.508Z",
"created_by": "user_id",
"created_with": "api",
"param_history": [],
"projectType": "project_type",
"name": "project_name",
"pinned": false,
"archived": false,
"nucleusDatasetId": "nucleus_id",
"customGradersUsedOrDismissed": false,
"edgeCaseAlertsEnabled": false,
"turnOnLongHints": true,
"isAudioTranscription": false,
"useOldOnboarding": false,
"containsAdultContent": false,
"useRapidSmartTraining": false,
"useTextCollectionTemplate": false,
"datasetLinks": [
{
  "datasetId": "dataset_id",
  "datasetName": "dataset_name"
}
],
"taxonomy": null,
"isSampleProject": false,
"modelEvalProject": false
}
```

--------------------------------

### Create Task with Python SDK

Source: https://scale.com/docs/api-reference/image-and-video-tasks

Use the Scale Python SDK to create a task. This example includes error handling for duplicate resource IDs using ScaleDuplicateResource.

```python
from scaleapi.tasks import TaskType
from scaleapi.exceptions import ScaleDuplicateResource

payload = dict(
    "instruction": "**Instructions:** Please label all the things",
    "attachment": "https://i.imgur.com/iDZcXfS.png",
    "attachment_type": "image",
    "annotation_attributes": { "newKey": {
            "type": "type",
            "description": "description",
            "choices": "choices",
            "conditions": {
                "label_condition": ["car", "car2"],
                "attribute_conditions": {
                    "newKey": "New Value",
                    "newKey-1": "New Value"
                }
            }
        } },
    "allow_unlabeled": False,
    "metadata": {
        "newKey": "New Value",
        "newKey-1": "New Value"
    },
    "project": "Project Name",
    "batch": "Batch Name",
    "callback_url": "http://www.example.com/callback",
    "labels": [["vehicle"], "vehicle 2", "vehicle 3"],
    "context_attachments": [{ "attachment": "attachment" }, { "attachment": "attachment2" }],
    "unique_id": "unique_id",
    "clear_unique_id_on_error": True,
    "tags": ["tag", "tag2"]
  }
)

try:
    client.create_task(TaskType.Segmentannotation, **payload)
except ScaleDuplicateResource as err:
    print(err.message)  # If unique_id is already used for a different task
```

--------------------------------

### Annotation Configuration JSON

Source: https://scale.com/docs/api-reference/image-and-video-reference

Example configuration for defining annotation geometries, including object types and constraints like rotation.

```json
{
  "geometries": {
    "box": {
      "objects_to_annotate": [
        "traffic_sign",
        {
          "choice": "vehicle",
          "subchoices": [
          	"Car",
            {
              "choice": "truck_suv",
              "display": "truck or SUV"
            }
          ]
        },
        "pedestrian"
      ],
      "min_height": 5,
      "min_width": 5,
      "can_rotate": false
    },
    ...
  },
  ...
}
```

--------------------------------

### Ontology JSON structure example

Source: https://scale.com/docs/api-reference/data-engine-reference

Example of an ontology definition in JSON format, showing choices with descriptions and subchoices. The 'choice' field is required, while 'display' and 'description' are optional. Subchoices can be strings or nested OntologyChoice objects.

```json
ontology = [
  "Road",
  {
    "choice": "Vehicle",
    "description": "a means of carrying or transporting material",
    "subchoices": ["Car", "Truck", "Train", "Motorcycle"]
  },
  {
    "choice": "Pedestrian",
    "subchoices": [
      "Animal", 
      {"choice": "Ped_HeightOverMeter", "display": "Adult" }, 
      {"choice": "Ped_HeightUnderMeter", "display": "Child" }, 
    ]
  }
]
```

--------------------------------

### Create and Retrieve Fixless Audits with Python

Source: https://scale.com/docs/api-reference/fixless-audits

Demonstrates how to use the requests library to create a Fixless Audit via a PUT request and retrieve audit details via a GET request.

```python
import requests

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

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

# Create an audit 
body = {...} # FixlessAuditCreate
url = "https://api.scale.com/v1/audits"
response = requests.put(url, headers=headers, auth=(API_KEY, ''), json=body) # 201 response FixlessAudit
print(response.text)

# Get audits
url = "https://api.scale.com/v1/audits/?task_id=xxx&id=yyy" # provide task id or audit id
response = requests.get(url, headers=headers, auth=(API_KEY, '')) # 200 response FixlessAudit[]
print(response.text)
```

--------------------------------

### Ellipse annotation request configuration

Source: https://scale.com/docs/api-reference/image-and-video-reference

JSON example showing how to configure an ellipse annotation request with objects_to_annotate and annotation_attributes.

```json
{
    ...
    "geometries": {
        "ellipse": {
            "objects_to_annotate": ["wheel"]
        }
    },
    "annotation_attributes": {
        "position": {
            "type": "category",
            "description": "What is the position of this wheel?",
            "choices": [
              "front_left",
              "front_right",
              "back_left",
              "back_right",
            ]
        }
    },
    ...
}
```

--------------------------------

### Batch Response JSON Structure

Source: https://scale.com/docs/api-reference/batches

Example of the JSON structure returned for a batch object.

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

--------------------------------

### Image Task Response JSON Structure

Source: https://scale.com/docs/api-reference/image-and-video-reference

Example of the response object structure including annotations for boxes and polygons, along with global attributes.

```json
{
  "response": {
    "annotations": [
      {
        "type": "box",
        "label": "small vehicle",
        "attributes": {
          "moving": "yes"
        },
        "left": 2,
        "top": 4,
        "width": 3,
        "height": 5,
        "uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
      },
      {
        "type": "box",
        "label": "large vehicle",
        "attributes": {
          "moving": "yes"
        },
        "left": 7,
        "top": 5,
        "width": 14,
        "height": 5,
        "uuid": "0a6cd019-a014-4c67-bd49-c269ba08028a"
      },
      {
        "type": "polygon",
        "label": "car",
        "vertices": [
          {
            "x": 123,
            "y": 10
          },
          {
            "x": 140,
            "y": 49
          },
          {
            "x": 67,
            "y": 34
          }
        ],
        "uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef43"
      },
      { ... },
      { ... }
    ],
    "global_attributes": {
      "driving": "Yes",
      "night": "No"
    }
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}
```

--------------------------------

### List Batches with Python requests

Source: https://scale.com/docs/api-reference/batches

Uses the requests library to perform a GET request to the batches endpoint with query parameters for filtering and pagination.

```python
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)
```

--------------------------------

### Create Image Annotation Task in Python

Source: https://scale.com/docs/api-reference/image-and-video-reference

This example demonstrates how to send a POST request to the Scale API to create an image annotation task, including geometry configurations for boxes, polygons, lines, and cuboids.

```python
import requests

url = "https://api.scale.com/v1/task/imageannotation"

payload = {
    "instruction": "**Instructions:** Please label all the things",
    "attachment": "https://i.imgur.com/iDZcXfS.png",
    "geometries": {
        "box": {
            "min_height": None,
            "min_width": None,
            "can_rotate": None,
            "integer_pixels": None
        },
        "polygon": {
            "min_vertices": None,
            "max_vertices": None
        },
        "line": {
            "min_vertices": None,
            "max_vertices": None
        },
        "cuboid": {
            "min_height": None,
            "min_width": None,
            "camera_intrinsics": {
                "fx": None,
                "fy": None,
                "cx": None,
                "cy": None,
                "skew": None,
                "scalefactor": None
            },
            "camera_rotation_quaternion": {
                "w": None,
                "x": None,
                "y": None,
                "z": None
            },
            "camera_height": None
        }
    },
    "padding": None,
    "paddingX": None,
    "paddingY": None,
    "priority": None
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

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

print(response.text)
```

--------------------------------

### List Projects via REST API

Source: https://scale.com/docs/api-reference/projects

Uses the requests library to perform a GET request to the projects endpoint with HTTP Basic Authentication.

```python
import requests
from requests.auth import HTTPBasicAuth

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

# Headers to specify the type of response we accept (JSON in this case)
headers = {"accept": "application/json"}

# Authentication using HTTP Basic Auth; provide your API key as the username
# No password is required, so the password field is empty
auth = HTTPBasicAuth('{{ApiKey}}', '')  

# Performing a GET request to the API with headers and authentication
response = requests.get(url, headers=headers, auth=auth)

# Printing the text content of the response from the API
print(response.text)
```

--------------------------------

### Example Response for Lidar Annotation Task

Source: https://scale.com/docs/api-reference/sensor-fusion-lidar-tasks

Shows the JSON response returned after creating a Lidar annotation task. It includes callback_url, created_at, instruction, is_test, params, status, task_id, and type.

```json
{
  "callback_url": "http://www.example.com/callback",
  "created_at": "2019-01-16T21:03:33.166Z",
  "instruction": "Annotate the *vehicles* and *pedestrians* in the image.",
  "is_test": false,
  "params": {},
  "status": "pending",
  "task_id": "5a99e20de50d4979ce6d291e",
  "type": "lidarannotation"
}
```

--------------------------------

### GET /v1/batches

Source: https://scale.com/docs/api-reference/batches

This endpoint lists all batches in descending order based on created_at. It supports pagination via limit and offset parameters, and allows filtering by project, status, detailed progress, and time range.

```APIDOC
## GET /v1/batches

### Description
This endpoint lists all batches in descending order based on created_at. It supports pagination via limit and offset parameters, and allows filtering by project, status, detailed progress, and time range.

### Method
GET

### Endpoint
/v1/batches

### Parameters
#### Query Parameters
- **project** (string) - Optional - Project name to filter batches by.
- **status** (string) - Optional - Status to filter batches by (staging or in_progress or completed).
- **detailed** (boolean) - Optional - Get details about the progress of the batches.
- **start_time** (string) - Optional - The minimum value of created_at for batches to be returned.
- **end_time** (string) - Optional - The maximum value of created_at for batches to be returned.
- **limit** (integer) - Optional - Page size (implied by pagination description).
- **offset** (integer) - Optional - Number of results to skip (implied by pagination description).

### Request Example
```
GET 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
```

### Response
#### Success Response (200)
- **completed_at** (string) - Timestamp when the batch was completed.
- **created_at** (string) - Timestamp when the batch was created.
- **metadata** (object) - Additional metadata.
- **name** (string) - Name of the batch.
- **project** (string) - Project name.
- **status** (string) - Status of the batch.

#### Response Example
```json
{
  "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"
}
```
```

--------------------------------

### Text Collection Taxonomy and param_chunks Example

Source: https://scale.com/docs/rapid-or-taxonomy-chunking

Example taxonomy for text collection with fields of type category, text, and field_set. The param_chunks example shows how to group field IDs for text collection tasks.

```json
{
  "fields": [
    {
      "type": "category",
      "field_id": "is_green",
      "title": "Does the picture include the color green?",
      "required": true,
      "choices": [
        {
          "label":"Yes",
          "value":"yes",
        },
        {
          "label":"No",
          "value":"no",
        }
      ],
    },
    {
      "type": "text",
      "field_id": "description",
      "title": "Describe this picture."
    },
    {
      "type": "field_set",
      "field_id": "vehicle",
      "title": "A vehicle in the image",
      "fields": [
        {
          "type": "text",
          "field_id": "vehicle_type",
          "title": "What type of vehicle is this?"
        },
        {
          "type": "number",
          "field_id": "num_wheels",
          "title": "How many wheels does this vehicle have?"
        }
      ]
    }
  ]
}

```

```javascript
param_chunks: [
  ['is_green', 'description'],
  ['vehicle']
]

```

--------------------------------

### Assemble and Serialize Scene

Source: https://scale.com/docs/api-reference/sensor-fusion-reference

Create a list of sensors, instantiate the Scene object, and use JSONBinaryEncoder to write the data to an .sfs file.

```text
### CREATE SENSORS ###
lidar_sensor = generate_lidar_sensor(lidar_dataframes, lidar_timestamps, all_poses_world)
camera_sensors = [
    generate_camera_sensor(camera.name, camera_timestamps[camera.name], all_poses_world)
    for camera in cameras
] 

sensors = camera_sensors + [lidar_sensor]

### ASSEMBLE SCENE ####
scene = sfio.Scene(
    sensors=sensors, time_offset=minimum_timestamp, time_unit="microseconds"  # type: ignore
)

# convert the Scene object to an sfs object
sfs_scene = sfio.model_converters.sfs.to_scene_spec_sfs(scene)

encoder = sfio.JSONBinaryEncoder()
encoder.write_file(os.path.join(SAMPLE, "example_scene.sfs"), sfs_scene) # type: ignore
```

--------------------------------

### Retrieve a project with the Scale Python SDK

Source: https://scale.com/docs/api-reference/projects

Use the ScaleClient.get_project method to retrieve project details. Initialize the client with your API key and pass the project name. The response is printed as a dictionary.

```python
import scaleapi

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

# Define the project name you want to retrieve
project_name = "kitten_labeling"

# Retrieve the project details
project = client.get_project(project_name=project_name)

# Print the project details
print(project.as_dict())
```

--------------------------------

### List Projects via Python SDK

Source: https://scale.com/docs/api-reference/projects

Uses the ScaleClient to retrieve and iterate through project details.

```python
import scaleapi

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

# Retrieve the list of all projects
projects = client.get_projects()

# Iterate over the projects and print their details
for project in projects:
    print(project.as_dict())
```

--------------------------------

### Create a Batch using Python SDK

Source: https://scale.com/docs/api-reference/batches

Uses the ScaleClient from the scaleapi library to create a new batch.

```python
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())
```

--------------------------------

### Authenticate with Python SDK

Source: https://scale.com/docs/api-reference/authentication

Initialize the ScaleClient using your API key.

```python
import scaleapi
client = scaleapi.ScaleClient('{{ApiKey}}')
```

--------------------------------

### Error Response Examples

Source: https://scale.com/docs/api-reference/errors

Examples of error response structures returned by the Scale API for common failure scenarios, including missing attachments, download failures, and attachment processing errors.

```APIDOC
## Error Response Examples

### Description
These examples illustrate the structure and content of error messages returned by the Scale API in different situations.

### Error: Missing Attachment Parameter

#### Description
This error occurs when a request is made without including an attachment or attachments parameter.

#### Response Example
```json
{
  "status_code": 400,
  "error": "Please include an attachment or attachments parameter."
}
```

### Error: Attachment Download Failure

#### Description
This error indicates that one or more attachments could not be downloaded, possibly due to connectivity issues or invalid URLs.

#### Response Example
```json
{
    "error": "One or more attachments could not be downloaded.",
    "attachments": [
        {
            "statusCode": 403,
            "url": "http://example.com/kitten.png"
        }
    ]
}
```

### Error: Attachment Processing Failure

#### Description
This error provides specific details about frames that failed processing, including the frame number and error message.

#### Response Example
```json
{
    "error": "One or more attachments could not be downloaded.",
    "frames": [
        {
            "frame": 10,
            "message": "Invalid JSON Format: Unexpected end of JSON input",
            "attachment": {
                "statusCode": 200,
                "url": "http://example.com/lidar/frame10.json"
            }
        }
    ]
}
```
```

--------------------------------

### Cancel a task with HTTP API or Python SDK

Source: https://scale.com/docs/api-reference/tasks

Two Python examples for canceling a task: one using the raw HTTP API with requests and one using the Scale Python SDK. Both require an API key and a task ID. The HTTP example sends a POST to the /cancel endpoint with an optional clear_unique_id query parameter; the SDK example calls client.cancel_task(task_id).

```python
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/task/576ba74eec471ff9b01557cc/cancel?clear_unique_id=true"

# 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
import scaleapi

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

# Define the task ID to cancel
task_id = "601ba74eec471ff9b01557cc"  # Replace with your actual task ID

# Cancel the task
client.cancel_task(task_id)

# Print confirmation
print(f"Task '{task_id}' has been canceled.")
```

--------------------------------

### Python: Create LIDAR Linking Task

Source: https://scale.com/docs/api-reference/sensor-fusion-lidar-tasks

Sends a POST request to https://api.scale.com/v1/task/lidarlinking with the required payload fields. Replace 'your_api_key_here' with your actual API key. The response is printed as text.

```python
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/task/lidarlinking"

# Define the payload for the LIDAR linking task
payload = {
    "instruction": "**Instructions:** Please label all the things",
    "annotation_type": "imageannotation",
    "can_add_annotations": True,
    "can_edit_annotations": True,
    "can_edit_annotation_positions": True,
    "can_delete_annotations": True,
    "lidar_task": "607385eadfd77d0029a84084"
}

# 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)
```

--------------------------------

### Example response JSON for updating unique_id

Source: https://scale.com/docs/api-reference/tasks

Example JSON response from the Scale Update Task Unique ID endpoint. Shows the updated task object with the new unique_id value. Note the missing comma after the unique_id field in the source.

```json
{
  "task_id": "601ba74e98762345bcbcaaaa",
  "created_at": "2021-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "imageannotation",
  "status": "completed",
  "instruction": "Label every object in this image",
  "params": {
    "attachment": "https://example.com/image.jpg",
    "geometries": {
      "box": {
        "objects_to_annotate": [
          "vehicle",
          "pedestrian"
        ]
      }
    }
  },
  "unique_id": "new_unique_id"
  "metadata": {}
}
```

--------------------------------

### List Batches with Python SDK

Source: https://scale.com/docs/api-reference/batches

Uses the ScaleClient to retrieve batches with optional filters for project, status, and time ranges.

```python
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())
```

--------------------------------

### Line annotation response example

Source: https://scale.com/docs/api-reference/image-and-video-reference

Example response for a line annotation task. The response includes an annotations array with line objects containing type, label, vertices, and uuid. The uuid can be used to track the same object across frames in video tasks.

```json
{
  "response": {
    "annotations": [
      {
        "type": "line",
        "label": "solid line",
        "vertices": [
            {
                "x": 123,
                "y": 10
            },
            {
                "x": 140,
                "y": 49
            },
            {
                "x": 67,
                "y": 34
            }
        ],
        "uuid": "65ec1f52-5902-4b39-bea9-ab6b4d58ef42"
      },
      { ... },
      { ... }
    ]
  },
  "task_id": "5774cc78b01249ab09f089dd",
  "task": {
    // populated task for convenience
    ...
  }
}
```

--------------------------------

### Create Video Annotation Task with Python SDK

Source: https://scale.com/docs/api-reference/image-and-video-tasks

Uses the Scale Python SDK to define task parameters and create a video annotation task. Includes error handling for duplicate unique IDs.

```python
from scaleapi.tasks import TaskType
from scaleapi.exceptions import ScaleDuplicateResource

payload = dict(
    "instruction": "**Instructions:** Please label all the things",
    "attachments": ["https://static.scale.com/scaleapi-lidar-images/2011_09_29_drive_0071_sync/image_02/data/0000000005.png", "https://static.scale.com/scaleapi-lidar-images/2011_09_29_drive_0071_sync/image_02/data/0000000008.png"],
    "attachment_type": "image",
    "geometries": {
        "box": {
            "min_height": 10,
            "min_width": 10,
            "can_rotate": True,
            "integer_pixels": False
        },
        "polygon": {
            "min_vertices": 10,
            "max_vertices": 20,
            "objects_to_annotate": ["large vehicle"]
        },
        "line": {
            "min_vertices": 10,
            "max_vertices": 20,
            "objects_to_annotate": ["large vehicle"]
        },
        "point": { "objects_to_annotate": ["large vehicle", "large vehicle"] },
        "cuboid": {
            "min_height": 10,
            "min_width": 10,
            "camera_intrinsics": {
                "fx": 10,
                "fy": 10,
                "cx": 10,
                "cy": 10,
                "skew": 10,
                "scalefactor": 10
            },
            "camera_rotation_quaternion": {
                "w": 10,
                "x": 10,
                "y": 10,
                "z": 10
            },
            "camera_height": 10
        },
        "ellipse": { "objects_to_annotate": ["large vehicle"] }
    },
    "events_to_annotate": ["event_1_name", "event_2_name"],
    "frame_rate": 1,
    "start_time": 10,
    "padding": 10,
    "paddingX": 10,
    "metadata": {
        "newKey": "New Value",
        "newKey-1": "New Value"
    },
    "priority": 30,
    "project": "Project Name",
    "batch": "Batch Name",
    "callback_url": "http://www.example.com/callback",
    "attachment": "attachment_url",
    "duration_time": 10,
    "paddingY": 10,
    "unique_id": "unique_id",
    "clear_unique_id_on_error": True,
    "tags": ["tag1", "tag2"]
)

try:
    client.create_task(TaskType.VideoAnnotation, **payload)
except ScaleDuplicateResource as err:
    print(err.message)  # If unique_id is already used for a different task
```

--------------------------------

### GET /v1/batches/{batchName}

Source: https://scale.com/docs/api-reference/batches

Retrieves the details of a batch with the specified batch name.

```APIDOC
## GET /v1/batches/{batchName}

### Description
Retrieves the details of a batch with the specified batch name.

### Method
GET

### Endpoint
https://api.scale.com/v1/batches/{batchName}

### Parameters
#### Path Parameters
- **batchName** (string) - Required - The name of the batch to retrieve.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **project** (string) - The project associated with the batch.
- **name** (string) - The name of the batch.
- **callback** (string) - The callback email address.
- **status** (string) - The status of the batch (e.g., "in_progress").
- **created_at** (string) - The creation timestamp of the batch.
- **metadata** (object) - Additional metadata associated with the batch.

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

--------------------------------

### Retrieve batch details with Python SDK

Source: https://scale.com/docs/api-reference/batches

Uses the ScaleClient to fetch batch information by name. Requires the scaleapi package.

```python
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())
```