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

<Steps>
  <Step title="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_`.
  </Step>

  <Step title="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 <Tooltip tip="You can filter by task status">all completed tasks</Tooltip> from a project or a batch
    * You can download tasks directly from a specific delivery
    * You can <Tooltip tip="API allows you to download tasks by completion date for your data pipelines">continuously download</Tooltip> recently completed tasks from a project
  </Step>

  <Step title="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](/v2/tasks) from a project or batch with different parameters
    * [Download tasks from a given delivery](/v2/delivery) from a project
  </Step>
</Steps>

## 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](/v2/task) or [query for tasks](/v2/tasks) 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)
```