​
Your First API Call

1

Getting Your API Key

Scale API Key can be retrieved by logging into the Scale dashboard. In the customer dashboard, click your profile and visit the “API Key” section to get your “Live API Key”, which should start with live_.

2

Decide Which Tasks You Want to Download

You can browse your projects and batches in the Scale Dashboard. API supports searching tasks by name or ID of the associated projects, batches or deliveries.

Scale API offers multiple ways to search tasks that you want to download:

  • You can download from a project or a batch
  • You can download tasks directly from a specific delivery
  • You can recently completed tasks from a project
3

Downloading Tasks

Below you can find an example of how to download completed tasks from a project: Retrieving Tasks

You can also explore other ways to download tasks from Scale API:

​
Downloading Tasks

See our API Reference to retrieve a single task or query for tasks in a project or batch.

# Downloads all completed tasks from a project and saves them to a jsonl file
import json
import requests


API_KEY = 'live_...'
PROJECT_NAME = 'My Test Project'

def get_tasks_by_project_name(project_name: str):
    tasks = []
    params = {
        "project_name": project_name,
        "status": "completed",
        "limit": "100",
    }

    should_fetch = True

    while should_fetch:
        response = requests.request(
            "GET",
            url="https://api.scale.com/v2/tasks",
            params=params,
            headers={
                "Accept": "application/json",
                "Authorization": f"Bearer {API_KEY}",
            },
        )
        json_resp = response.json()

        next_token = json_resp.get('next_token')
        if next_token:
            params['next_token'] = next_token
        else:
            should_fetch = False

        tasks.extend(json_resp['tasks'])

    return tasks


if __name__ == "__main__":
    tasks = get_tasks_by_project_name(PROJECT_NAME)

    with open(f'{PROJECT_NAME}.jsonl', 'w+') as f:
        for task in tasks:
            json.dump(task, f)
            f.write('\n')

​
Uploading Tasks to Scale

You can use Scale Python SDK to upload tasks to Scale.

​
Initializing Scale SDK Client

import scaleapi

API_KEY = "live_...."
client = scaleapi.ScaleClient(API_KEY)

First you are expected to create a batch in the project.

​
Creating a Batch

from scaleapi.exceptions import (
    ScaleException,
    ScaleResourceNotFound,
)

def get_or_create_batch(client: scaleapi.ScaleClient, project_name, batch_name):
    try:
        batch = client.get_batch(batch_name)
        return batch
    except ScaleResourceNotFound:
        batch = client.create_batch(project_name, batch_name, "")
        return batch
    except ScaleException as err:
        raise Exception(f"❌ ERROR Batch Creation: {err.message}") from err

batch = get_or_create_batch(client, project.name, "test_api_batch_20240708")
print(f"Batch: {batch.name}")

​
Creating Tasks

Once a batch is created, then the tasks can be created within that batch. Each task is expected to have certain information sent in the request payload that corresponds to the project.

# Those variables are specific to each project and need to be aligned with Scale before sending them
template_variables = {
    "id": "0",
    "prompt": "Hello world!",
    "base_model_response": "..."
    "test_modeL_response": "..."
    "languageCode": "en_US",
}

# Task Payload
payload = {
    "project": project.name,
    "batch": batch.name,
    "template_variables": template_variables,
    "unique_id":"unique_id_12345"
}

def create_task_request(client: scaleapi.ScaleClient, payload):
    try:
        task = client.create_task(TaskType.Chat, **payload)
        return task.id
    except ScaleDuplicateResource as dup_err:  # Existing Task
        print(f"Task already exists: {dup_err.message}")
    except ScaleException as err:
        print(f"❌ ERROR Task Creation: {err.message}")
        return None

task_id = create_task_request(client, payload)
Authentication