Skip to main content
GET
/
v2
/
tasks
API_KEY='live_...'
PARAMS='project_name=My+Test+Project&status=completed&limit=1'
curl --request GET \
    --url "https://api.scale.com/v2/tasks?$PARAMS" \
    --header "Authorization: Bearer $API_KEY"
{
  "tasks": [
    {
      "task_id": "task_123",
      "project": "project_123",
      "batch": "batch_123",
      "status": "completed",
      "created_at": "2025-01-01T08:31:03.169Z",
      "completed_at": "2025-01-02T04:00:39.923Z",
      "threads": [
        {
          "id": "thread_0",
          "turns": [
            {
              "id": "turn_0",
              "messages": [
                {
                  "content": {
                    "text": "This is an example prompt"
                  },
                  "role": "user",
                  "source_id": "user",
                  "annotations": []
                },
                {
                  "content": {
                    "text": "This is the base model response"
                  },
                  "role": "assistant",
                  "source_id": "base_model",
                  "model_parameters": {
                    "model": "scale-gpt-1.5-turbo",
                    "temperature": 0.9,
                    "max_completion_tokens": 2048
                  },
                  "annotations": [
                    {
                      "key": "instruction_following",
                      "value": 3
                    },
                    {
                      "key": "truthfulness",
                      "value": 2
                    },
                    {
                      "key": "conciseness",
                      "value": 3
                    },
                    {
                      "key": "format",
                      "value": 3
                    },
                    {
                      "key": "safety",
                      "value": 3
                    },
                    {
                      "key": "overall",
                      "value": 5
                    }
                  ]
                },
                {
                  "content": {
                    "text": "This is test model response"
                  },
                  "role": "assistant",
                  "source_id": "test_model",
                  "model_parameters": {
                    "model": "scale-gpt-2.0",
                    "temperature": 0.9,
                    "max_completion_tokens": 2048
                  },
                  "annotations": [
                    {
                      "key": "instruction_following",
                      "value": 2
                    },
                    {
                      "key": "truthfulness",
                      "value": 1
                    },
                    {
                      "key": "truthfulness_justification",
                      "value": "The response incorrectly classifies..."
                    },
                    {
                      "key": "conciseness",
                      "value": 2
                    },
                    {
                      "key": "format",
                      "value": 3
                    },
                    {
                      "key": "safety",
                      "value": 3
                    },
                    {
                      "key": "overall",
                      "value": 3
                    }
                  ]
                }
              ],
              "annotations": [
                {
                  "key": "selected_model_id",
                  "value": "base_model"
                },
                {
                  "key": "likert_value",
                  "value": 2
                },
                {
                  "key": "justification",
                  "value": "@Response 1 is better than @Response 2. @Response 2 has an issue in Truthfulness ..."
                }
              ]
            }
          ],
          "annotations": []
        }
      ]
    }
  ],
  "next_token": "imatoken123"
}
Every request sent to Scale’s API requires authentication. In short, your API Key is the Bearer token. See the Authentication section for more details.

​
Required query parameters

You are expected to provide one of the following to start downloading tasks:
  • Project (project_id or project_name)
  • Batch (batch_id or batch_name)

​
Example Code

# Downloads all completed tasks from a batch
import json
import requests


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

def get_tasks_by_batch(project_name: str, batch_name: str):
    tasks = []
    params = {
        "project_name": project_name,
        "batch_name": batch_name,
        "status": "completed"
    }

    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_batch(PROJECT_NAME, BATCH_NAME)

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

Authorizations

​
Authorization
string
header
required

Your API Key is the Bearer token. See the Authentication section to learn how to access your key.

Query Parameters

​
project_id
string

Scale's unique identifier for the project.

Example:

"project_abc123"

​
project_name
string

The name of the project.

Example:

"My Scale Project"

​
batch_id
string

Scale's unique identifier for the batch.

Example:

"batch_abc123"

​
batch_name
string

The name of the batch.

Example:

"My Scale Batch"

​
status
enum<string>

The current status of the task, indicating whether it is pending, completed, error, or canceled.

Available options:
pending,
completed,
canceled,
error
​
completed_after
string<date-time>

Tasks with a completed_at after the given date will be returned. A timestamp formatted as an ISO 8601 date-time string.

​
completed_before
string<date-time>

Tasks with a completed_at before the given date will be returned. A timestamp formatted as an ISO 8601 date-time string.

​
limit
integer

Limit the number of entities returned.

Required range: 1 <= x <= 100
​
next_token
string

A token used to retrieve the next page of results if there are more. You can find the next_token in your last request.

​
expand
enum<string>[]

List of fields to expand in the response.

​
opts
enum<string>[]

List of properties to include in the task response.

Response

List of completed tasks.

​
tasks
object[]
required

Array of task objects

​
next_token
string

A token used to retrieve the next page of results if there are more. You can find the next_token in your last request

⌘I