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

# Quickstart

> How to use Scale APIs

## 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](https://dashboard.scale.com), click your profile and visit the "[API Key](https://dashboard.scale.com/settings/apikey)" 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](https://dashboard.scale.com).
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 all completed tasks (You can filter by task status) from a project or a batch
* You can download tasks directly from a specific delivery
* You can continuously download (API allows you to download tasks by completion date for your data pipelines) recently completed tasks from a project

**3. Downloading Tasks**

Below you can find an example of how to download completed tasks from a project: [Downloading Tasks](#downloading-tasks)

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

* [Download multiple tasks](https://docs.genai.scale.com/v2/tasks.md) from a project or batch with different parameters
* [Download tasks from a given delivery](https://docs.genai.scale.com/v2/delivery.md) from a project

## Initializing [Scale Python SDK](https://github.com/scaleapi/scaleapi-python-client)

First install the Python SDK.

```bash theme={null}
pip install --upgrade scaleapi
```

Then use your API key to initialize the client.

```python theme={null}
import scaleapi

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

## Downloading Tasks

See our API Reference to [retrieve a single task](https://docs.genai.scale.com/v2/task.md) or [query for tasks](https://docs.genai.scale.com/v2/tasks.md) in a project or batch.

```python theme={null}
# Downloads all completed tasks from a project and saves them to a jsonl file
import json

PROJECT_NAME = "My Test Project"

def get_tasks_by_project_name(project_name: str):
    tasks_generator = client.v2_get_tasks(
        project_name=project_name,
        status="completed",
        limit=100,
    )
    tasks = list(tasks_generator)
    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.model_dump(mode='json'), f)
            f.write("\n")
```

## Uploading Tasks to Scale

### Creating a Batch

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

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

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