Metadata-Version: 2.1
Name: scaleapi
Version: 2.19.0
Summary: The official Python client library for Scale AI, the Data Platform for AI
Home-page: https://github.com/scaleapi/scaleapi-python-client
Author: Scale AI
Author-email: support@scale.com
Keywords: scale,scaleapi,tasks,categorization,labeling,annotation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: urllib3>=1.26.0
Requires-Dist: python_dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1

*********************
Scale AI | Python SDK
*********************

If you use earlier versions of the SDK, please refer to `v1.0.4 documentation <https://github.com/scaleapi/scaleapi-python-client/blob/release-1.0.4/README.rst>`_.

If you are migrating from earlier versions to v2,  please refer to `Migration Guide to v2 <https://github.com/scaleapi/scaleapi-python-client/blob/master/docs/migration_guide.md>`_.

|pic1| |pic2| |pic3|

.. |pic1| image:: https://pepy.tech/badge/scaleapi/month
  :alt: Downloads
  :target: https://pepy.tech/project/scaleapi
.. |pic2| image:: https://img.shields.io/pypi/pyversions/scaleapi.svg
  :alt: Supported Versions
  :target: https://pypi.org/project/scaleapi
.. |pic3| image:: https://img.shields.io/github/contributors/scaleapi/scaleapi-python-client.svg
  :alt: Contributors
  :target: https://github.com/scaleapi/scaleapi-python-client/graphs/contributors

Installation
____________

Install with PyPI (pip)

.. code-block:: bash

    $ pip install --upgrade scaleapi

or install with Anaconda (conda)

.. code-block:: bash

    $ conda install -c conda-forge scaleapi

Usage
_____

.. code-block:: python

    import scaleapi

    client = scaleapi.ScaleClient("YOUR_API_KEY_HERE")

If you need to use a proxy to connect Scale API, you can feed ``proxies``, ``cert`` and ``verify`` attributes of the python ``requests`` package during the client initialization.
Proxy support is available with SDK version 2.14.0 and beyond.

`Documentation of Proxies usage in requests package`__

__ https://requests.readthedocs.io/en/latest/user/advanced/#proxies

.. code-block:: python

    proxies = { 'https': 'http://10.10.1.10:1080' }

    client = scaleapi.ScaleClient(
                api_key="YOUR_API_KEY_HERE",
                proxies=proxies,
                cert='/path/client.cert',
                verify=True
            )

Tasks
_____

Most of these methods will return a `scaleapi.Task` object, which will contain information
about the json response (task_id, status, params, response, etc.).

Any parameter available in `Scale's API documentation`__ can be passed as an argument option with the corresponding type.

__ https://scale.com/docs/api-reference/data-engine-reference#tasks-object-overview

The following endpoints for tasks are available:

Create Task
^^^^^^^^^^^

This method can be used for any Scale supported task type using the following format:

.. code-block:: python

    client.create_task(TaskType, ...task parameters...)

Passing in the applicable values into the function definition. The applicable fields and further information for each task type can be found in `Scale's API documentation`__.

__ https://scale.com/docs/api-reference

.. code-block:: python

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

    payload = dict(
        project = "test_project",
        callback_url = "http://www.example.com/callback",
        instruction = "Draw a box around each baby cow and big cow.",
        attachment_type = "image",
        attachment = "http://i.imgur.com/v4cBreD.jpg",
        unique_id = "c235d023af73",
        geometries = {
            "box": {
                "objects_to_annotate": ["Baby Cow", "Big Cow"],
                "min_height": 10,
                "min_width": 10,
            }
        },
    )

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

Data collection (``TaskType.DataCollectionV2``) tasks take an ``upload_type`` that sets the rest of
the payload's shape. Fields that are not part of the upload type's schema are rejected. Tasks are
deduplicated on ``(project, metadata.id)``, so resending the same ``metadata.id`` returns the
existing task instead of creating a new one.

.. code-block:: python

    from scaleapi.tasks import TaskType

    payload = dict(
        project = "test_project",
        upload_type = "video-annotation",
        video_attachment = [
            {"url": "s3://bucket/left.mp4", "sensor_id": "left", "name": "left"},
        ],
        hypothesis = "s3://bucket/prelabels.sfs",  # optional
        metadata = {"id": "recording-0001"},
    )

    task = client.create_task(TaskType.DataCollectionV2, **payload)

    # If the task's processing pipeline fails to start, the request still succeeds
    # and the task comes back with an "error" status.
    if task.status == "error":
        print(task.as_dict())


Retrieve a task
^^^^^^^^^^^^^^^

Retrieve a task given its id. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#retrieve-a-task

.. code-block :: python

    task = client.get_task("30553edd0b6a93f8f05f0fee")
    print(task.status)  # Task status ("pending", "completed", "error", "canceled")
    print(task.response) # If task is complete


Task Attributes
^^^^^^^^^^^^^^^

The older ``param_dict`` attribute is now replaced with a method ``as_dict()`` to return a task's all attributes as a dictionary (JSON).

.. code-block :: python

    task.as_dict()

    # {
    #  'task_id': '30553edd0b6a93f8f05f0fee',
    #  'created_at': '2021-06-17T21:46:36.359Z',
    #  'type': 'imageannotation',
    #  'status': 'pending',
    #   ....
    #  'params': {
    #   'attachment': 'http://i.imgur.com/v4cBreD.jpg',
    #   'attachment_type': 'image',
    #   'geometries': {
    #    'box': {
    #     'objects_to_annotate': ['Baby Cow', 'Big Cow'],
    #     'min_height': 10,
    #     'min_width': 10,
    #     ...
    #   },
    #  'project': 'My Project',
    #  ...
    # }

First-level attributes of Task are also accessible with ``.`` annotation as the following:

.. code-block :: python

    task.status                   # same as task.as_dict()["status"]
    task.params["geometries"]     # same as task.as_dict()["params"]["geometries"]
    task.response["annotations"]  # same as task.as_dict()["response"]["annotations"]


Accessing ``task.params`` child objects directly at task level is **deprecated**. Instead of ``task.attribute``, you should use ``task.params["attribute"]`` for accessing objects under `params`.

.. code-block :: python

    task.params["geometries"]   # task.geometries is DEPRECATED
    task.params["attachment"]   # task.attachment is DEPRECATED

If you use the ``limited_response = True`` filter in ``get_tasks()``, you will only receive the following attributes: ``task_id``, ``status``, ``metadata``, ``project`` and ``otherVersion``.

Retrieve List of Tasks
^^^^^^^^^^^^^^^^^^^^^^

Retrieve a list of `Task` objects, with filters for: ``project_name``, ``batch_name``, ``type``, ``status``,
``review_status``, ``unique_id``, ``completed_after``, ``completed_before``, ``updated_after``, ``updated_before``,
``created_after``, ``created_before``, ``tags``, ``limited_response`` and ``limit``.

``get_tasks()`` is a **generator** method and yields ``Task`` objects.

*A generator is another type of function, returns an iterable that you can loop over like a list.
However, unlike lists, generators do not store the content in the memory.
That helps you to process a large number of objects without increasing memory usage.*

If you will iterate through the tasks and process them once, using a generator is the most efficient method.
However, if you need to process the list of tasks multiple times, you can wrap the generator in a ``list(...)``
statement, which returns a list of Tasks by loading them into the memory.

Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#retrieve-multiple-tasks

.. code-block :: python

    from scaleapi.tasks import TaskReviewStatus, TaskStatus

    tasks = client.get_tasks(
        project_name = "My Project",
        created_after = "2020-09-08",
        completed_before = "2021-04-01",
        status = TaskStatus.Completed,
        review_status = TaskReviewStatus.Accepted
    )

    # Iterating through the generator
    for task in tasks:
        # Download task or do something!
        print(task.task_id)

    # For retrieving results as a Task list
    task_list = list(tasks)
    print(f"{len(task_list)} tasks retrieved")

Get Tasks Count
^^^^^^^^^^^^^^^

``get_tasks_count()`` method returns the number of tasks with the given optional parameters for: ``project_name``, ``batch_name``, ``type``, ``status``,
``review_status``, ``unique_id``, ``completed_after``, ``completed_before``, ``updated_after``, ``updated_before``,
``created_after``, ``created_before`` and ``tags``.

.. code-block :: python

    from scaleapi.tasks import TaskReviewStatus, TaskStatus

    task_count = client.get_tasks_count(
        project_name = "My Project",
        created_after = "2020-09-08",
        completed_before = "2021-04-01",
        status = TaskStatus.Completed,
        review_status = TaskReviewStatus.Accepted
    )

    print(task_count)  # 1923


Cancel Task
^^^^^^^^^^^

Cancel a task given its id if work has not started on the task (task status is ``Queued`` in the UI). Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#cancel-task

.. code-block :: python

    task = client.cancel_task('30553edd0b6a93f8f05f0fee')

    # If you also want to clear 'unique_id' of a task while canceling
    task = client.cancel_task('30553edd0b6a93f8f05f0fee', clear_unique_id=True)

    # cancel() is also available on task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    task.cancel()

    # If you also want to clear 'unique_id' of a task while canceling
    task.cancel(clear_unique_id=True)


Audit a Task
^^^^^^^^^^^^

This method allows you to ``accept`` or ``reject`` completed tasks, along with support for adding comments about the reason for the given audit status, mirroring our Audit UI.
Check out `Scale's API documentation`__ for more information.

__ https://docs.scale.com/reference/audit-a-task

.. code-block :: python

    # Accept a completed task by submitting an audit
    client.audit_task('30553edd0b6a93f8f05f0fee', True)

    # Reject a completed task by submitting a comment with the audit
    client.audit_task('30553edd0b6a93f8f05f0fee', False, 'Rejected due to quality')

    # audit() is also available on Task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    task.audit(True)


Create a Fixless Audit
^^^^^^^^^^^^^^^^^^^^^^

Fixless audits record structured feedback on specific parts of a completed task's response (an annotation, a scene attribute, a missing object...) without modifying the response. They must be enabled for your project and require a team Admin or Manager API key.

Pass the response you audited as ``target_response_url``: the completed task's ``response['annotations']['url']``. Each feedback item has a ``Scope`` saying where it applies. ``frames`` is a single frame index or an inclusive ``(start, end)`` range. Errors take an ``ErrorCategory`` and a ``Severity`` (``Severity.Standard`` by default).

.. code-block :: python

    from scaleapi.audits import ErrorCategory, FeedbackItem, Scope, Severity

    task = client.get_task('30553edd0b6a93f8f05f0fee')

    audit = client.create_fixless_audit(
        task.id,
        task.response['annotations']['url'],
        accepted=False,
        comments='Two issues in the first second',
        feedback_items=[
            FeedbackItem.error(
                Scope.annotation('cuboid_12', frames=(0, 9)),
                ErrorCategory.Geometry,
                Severity.Severe,
                description='Box is too loose',
            ),
            FeedbackItem.error(
                Scope.point([412.0, 230.5], frames=4, sensor_id=0),
                ErrorCategory.Missing,
                description='Pedestrian not labeled',
            ),
            FeedbackItem.comment(Scope.scene(frames=0), 'Low light scene'),
        ],
    )

    # Also available on the Task object, along with its existing audits
    task.create_fixless_audit(task.response['annotations']['url'], accepted=True)
    audits = task.audits()  # newest first


Update A Task's Unique Id
^^^^^^^^^^^^^^^^^^^^^^^^^

Update a given task's unique_id. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#update-unique_id

.. code-block :: python

    task = client.update_task_unique_id('30553edd0b6a93f8f05f0fee', "new_unique_id")

    # update_unique_id() is also available on task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    task.update_unique_id("new_unique_id")


Clear A Task's Unique Id
^^^^^^^^^^^^^^^^^^^^^^^^^

Clear a given task's unique_id. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#delete-unique_id

.. code-block :: python

    task = client.clear_task_unique_id('30553edd0b6a93f8f05f0fee')

    # clear_unique_id() is also available on task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    task.clear_unique_id()


Set A Task's Metadata
^^^^^^^^^^^^^^^^^^^^^^^^^

Set a given task's ``metadata``. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#set-task-metadata

.. code-block :: python

    # set metadata on a task by specifying task id
    new_metadata = {'myKey': 'myValue'}
    task = client.set_task_metadata('30553edd0b6a93f8f05f0fee', new_metadata)

    # set metadata on a task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    new_metadata = {'myKey': 'myValue'}
    task.set_metadata(new_metadata)

Set A Task's Tags
^^^^^^^^^^^^^^^^^^^^^^^^^

Set a given task's ``tags``. This will replace all existing tags on a task. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#set-task-tag

.. code-block :: python

    # set a list of tags on a task by specifying task id
    new_tags = ["tag1", "tag2", "tag3"]
    task = client.set_task_tags('30553edd0b6a93f8f05f0fee', new_tags)

    # set a list of tags on a task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    new_tags = ["tag1", "tag2", "tag3"]
    task.set_tags(new_tags)

Add Tags to A Task
^^^^^^^^^^^^^^^^^^^^^^^^^

Add ``tags`` to a given task. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#delete-task-tag

.. code-block :: python

    # add a list of tags on a task by specifying task id
    tags_to_add = ["tag4", "tag5"]
    task = client.add_task_tags('30553edd0b6a93f8f05f0fee', tags_to_add)

    # add a list of tags on a task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    tags_to_add = ["tag4", "tag5"]
    task.add_tags(tags_to_add)

Delete Tags from A Task
^^^^^^^^^^^^^^^^^^^^^^^^^

Delete ``tags`` from a given task. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/tasks#delete-task-tag

.. code-block :: python

    # delete a list of tags on a task by specifying task id
    tags_to_delete = ["tag1", "tag2"]
    task = client.delete_task_tags('30553edd0b6a93f8f05f0fee', tags_to_delete)

    # delete a list of tags on a task object
    task = client.get_task('30553edd0b6a93f8f05f0fee')
    tags_to_delete = ["tag1", "tag2"]
    task.delete_tags(tags_to_delete)

Batches
_______

Create Batch
^^^^^^^^^^^^

Create a new Batch. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/batches#create-a-batch

.. code-block:: python

    batch = client.create_batch(
        project = "test_project",
        callback = "http://www.example.com/callback",
        batch_name = "batch_name_01_07_2021"
    )

    print(batch.name)  # batch_name_01_07_2021

Throws ``ScaleDuplicateResource`` exception if a batch with the same name already exists.

Finalize Batch
^^^^^^^^^^^^^^^

Finalize a Batch. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/batches#finalize-batch

.. code-block:: python

    client.finalize_batch(batch_name="batch_name_01_07_2021")

    # Alternative method
    batch = client.get_batch(batch_name="batch_name_01_07_2021")
    batch.finalize()

Check Batch Status
^^^^^^^^^^^^^^^^^^

Get the status of a Batch. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/batches#batch-status

.. code-block:: python

    client.batch_status(batch_name = "batch_name_01_07_2021")

    # Alternative via Batch.get_status()
    batch = client.get_batch("batch_name_01_07_2021")
    batch.get_status() # Refreshes tasks_{status} attributes of Batch
    print(batch.tasks_pending, batch.tasks_completed)

Retrieve A Batch
^^^^^^^^^^^^^^^^

Retrieve a single Batch. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/batches#batch-retrieval

.. code-block:: python

    batch = client.get_batch(batch_name = "batch_name_01_07_2021")

The older ``param_dict`` attribute is now replaced with a method ``batch.as_dict()`` to return a batch's all attributes as a dictionary (JSON).

List Batches
^^^^^^^^^^^^

Retrieve a list of Batches. Optional parameters are ``project_name``, ``batch_status``, ``exclude_archived``, ``created_after`` and ``created_before``.

``get_batches()`` is a **generator** method and yields ``Batch`` objects.

*A generator is another type of function, returns an iterable that you can loop over like a list.
However, unlike lists, generators do not store the content in the memory.
That helps you to process a large number of objects without increasing memory usage.*

When wrapped in a ``list(...)`` statement, it returns a list of Batches by loading them into the memory.

Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/batches#list-all-batches

.. code-block :: python

    from scaleapi.batches import BatchStatus

    batches = client.get_batches(
        batch_status=BatchStatus.Completed,
        created_after = "2020-09-08"
    )

    counter = 0
    for batch in batches:
        counter += 1
        print(f"Downloading batch {counter} | {batch.name} | {batch.project}")

    # Alternative for accessing as a Batch list
    batch_list = list(batches)
    print(f"{len(batch_list))} batches retrieved")

Projects
________

Create Project
^^^^^^^^^^^^^^

Create a new Project. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/projects#create-project

.. code-block:: python

    from scaleapi.tasks import TaskType

    project = client.create_project(
        project_name = "Test_Project",
        task_type = TaskType.ImageAnnotation,
        params = {"instruction": "Please label the kittens"},
    )

    print(project.name)  # Test_Project

Retrieve Project
^^^^^^^^^^^^^^^^

Retrieve a single Project. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/projects#project-retrieval

.. code-block:: python

    project = client.get_project(project_name = "test_project")

The older ``param_dict`` attribute is now replaced with a method ``project.as_dict()`` to return a project's all attributes as a dictionary (JSON).

List Projects
^^^^^^^^^^^^^

This function does not take any arguments. Retrieve a list of every Project.
Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/projects#list-all-projects

.. code-block :: python

    counter = 0
    projects = client.projects()
    for project in projects:
        counter += 1
        print(f'Downloading project {counter} | {project.name} | {project.type}')

Update Project
^^^^^^^^^^^^^^

Creates a new version of the Project. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/projects#update-project-parameters

.. code-block :: python

    data = client.update_project(
        project_name="test_project",
        patch=False,
        instruction="update: Please label all the stuff",
    )

Files
________

Files are a way of uploading local files directly to Scale storage or importing files before creating tasks.


Upload Files
^^^^^^^^^^^^^^

Upload a file. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/file-endpoints#file-upload

.. code-block:: python

    with open(file_name, 'rb') as f:
        my_file = client.upload_file(
            file=f,
            project_name = "test_project",
        )

The ``file.attachment_url`` can be used in place of attachments in task payload.


.. code-block:: python

    my_file.as_dict()

    # {
    #  'attachment_url': 'scaledata://606e2a0a46102303a130949/8ac09a90-c143-4154-9a9b-6c35121396d1f',
    #  'created_at': '2021-06-17T21:56:53.825Z',
    #  'id': '8ac09d70-ca43-4354-9a4b-6c3591396d1f',
    #  'mime_type': 'image/png',
    #  'project_names': ['test_project'],
    #  'size': 340714,
    #  'updated_at': '2021-06-17T21:56:53.825Z'
    # }

Import Files
^^^^^^^^^^^^^^

Import a file from a URL. Check out `Scale's API documentation`__ for more information.

__ https://scale.com/docs/api-reference/file-endpoints#file-import

.. code-block:: python

    my_file = client.import_file(
        file_url="http://i.imgur.com/v4cBreD.jpg",
        project_name = "test_project",
    )


After the files are successfully uploaded to Scale's storage, you can access the URL as ``my_file.attachment_url``, which will have a prefix like ``scaledata://``.

The attribute can be passed to the task payloads, in the ``attachment`` parameter.

.. code-block:: python

  task_payload = dict(
      ...
      ...
      attachment_type = "image",
      attachment = my_file.attachment_url,  # scaledata://606e2a30949/89a90-c143-4154-9a9b-6c36d1f
      ...
      ...
  )

Manage Teammates
________________

Manage the members of your Scale team via API. Check out `Scale Team API Documentation`__ for more information.

__ https://scale.com/docs/team-getting-started

List Teammates
^^^^^^^^^^^^^^

Lists all teammates in your Scale team.
Returns all teammates in a List of Teammate objects.

.. code-block:: python

    teammates = client.list_teammates()

Invite Teammate
^^^^^^^^^^^^^^^

Invites a list of email strings to your team with the provided role.
The available teammate roles are: 'labeler', 'member', or 'manager'.
Returns all teammates in a List of Teammate objects.

.. code-block:: python

    from scaleapi import TeammateRole

    teammates = client.invite_teammates(['email1@example.com', 'email2@example.com'], TeammateRole.Member)

Update Teammate Role
^^^^^^^^^^^^^^^^^^^^^

Updates a list of emails of your Scale team members with the new role.
The available teammate roles are: 'labeler', 'member', or 'manager'.
Returns all teammates in a List of Teammate objects.

.. code-block python

    from scaleapi import TeammateRole

    teammates = client.update_teammates_role(['email1@example.com', 'email2@example.com'], TeammateRole.Manager)

Example Scripts
_______________

A list of examples scripts for use.

* `cancel_batch.py`__ to concurrently cancel tasks in batches

__ https://github.com/scaleapi/scaleapi-python-client/blob/master/examples/cancel_batch.py


Error handling
______________

If something went wrong while making API calls, then exceptions will be raised automatically
as a `ScaleException` parent type and child exceptions:

- ``ScaleInvalidRequest``: 400 - Bad Request -- The request was unacceptable, often due to missing a required parameter.
- ``ScaleUnauthorized``: 401 - Unauthorized -- No valid API key provided.
- ``ScaleNotEnabled``: 402 - Not enabled -- Please contact sales@scaleapi.com before creating this type of task.
- ``ScaleResourceNotFound``: 404 - Not Found -- The requested resource doesn't exist.
- ``ScaleDuplicateResource``: 409 - Conflict -- Object already exists with same name, idempotency key or unique_id.
- ``ScaleTooManyRequests``: 429 - Too Many Requests -- Too many requests hit the API too quickly.
- ``ScaleInternalError``: 500 - Internal Server Error -- We had a problem with our server. Try again later.
- ``ScaleServiceUnavailable``: 503 - Server Timeout From Request Queueing -- Try again later.
- ``ScaleTimeoutError``: 504 - Server Timeout Error -- Try again later.

Check out `Scale's API documentation <https://scale.com/docs/api-reference/errors>`_ for more details.

For example:

.. code-block:: python

    from scaleapi.exceptions import ScaleException

    try:
        client.create_task(TaskType.TextCollection, attachment="Some parameters are missing.")
    except ScaleException as err:
        print(err.code)  # 400
        print(err.message)  # Parameter is invalid, reason: "attachments" is required


V2 API
______

If your project is using V2 API, you can use the ``.v2`` API client and also ``v2_get_tasks()`` to retrieve tasks in the V2 API format. See our `V2 API documentation`__.

__ https://docs.genai.scale.com/get-started/quickstart

.. list-table::
   :widths: 25 25 50
   :header-rows: 1

   * - Method
     - HTTP request
     - Description
   * - **get_task**
     - **GET** /v2/task
     - Get a Task
   * - **create_chat_task**
     - **POST** /v2/task
     - Create a Chat Task
   * - **get_tasks**
     - **GET** /v2/tasks
     - Get Multiple Tasks
   * - **get_batch**
     - **GET** /v2/batch
     - Get a Batch
   * - **create_batch**
     - **POST** /v2/batch
     - Create a Batch
   * - **get_batches**
     - **GET** /v2/batches
     - Get Multiple Batches
   * - **finalize_batch**
     - **POST** /v2/batch/finalize
     - Finalize a Batch
   * - **pause_batch**
     - **POST** /v2/batch/pause
     - Pause a Batch
   * - **resume_batch**
     - **POST** /v2/batch/resume
     - Resume a Batch
   * - **cancel_batch**
     - **POST** /v2/batch/cancel
     - Cancel a Batch
   * - **set_batch_metadata**
     - **POST** /v2/batch/metadata
     - Set Batch Metadata
   * - **get_project**
     - **GET** /v2/project
     - Get a Project
   * - **get_projects**
     - **GET** /v2/projects
     - Get Multiple Projects
   * - **get_deliveries**
     - **GET** /v2/deliveries
     - List All Deliveries
   * - **get_delivery**
     - **GET** /v2/delivery
     - Get Tasks in a Delivery
   * - **get_annotation**
     - **GET** /v2/annotation
     - Get an Annotation

For example:

.. code-block:: python

    # Get a task with the V2 format
    task = client.v2.get_task('30553edd0b6a93f8f05f0fee')

    # Get tasks in the V2 format (paged)
    tasks = client.v2.get_tasks(
        project_name = "My Project"
    )

    # Get tasks in the V2 format (generator)
    tasks = client.v2_get_tasks(
        project_name = "My Project"
    )

    # Iterating through the generator
    for task in tasks:
        # Download task or do something!
        print(task.task_id)

    # Create a chat task
    task = client.v2.create_chat_task(
        project_name="My Chat Project",
        template_variables={
            "prompt": "Explain quantum computing",
            "context": "For a general audience"
        }
    )

    # Get a batch
    batch = client.v2.get_batch('batch_123')

    # Create a batch
    batch = client.v2.create_batch(
        name="My New Batch",
        project="project_123"
    )

    # Finalize a batch
    batch = client.v2.finalize_batch('batch_123')


Troubleshooting
_______________

If you notice any problems, please contact our support via Intercom by logging into your dashboard, or, if you are Enterprise, by contacting your Engagement Manager.
