Get Multiple Tasks

Authentication

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.

Pagination

Remember to handle pagination when downloading large sets of tasks.

The API returns a maximum of 100 tasks per request (or less if you specify a limit). If your request returns more tasks than your specified limit, API response will also contain a next_token until you reach to the last page.You can set the next_token in your next request to continue downloading tasks from the next page.

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

Download All Completed Tasks From a Batch as JSONL

# 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. A unique identifier for the project.

Example:

"project_abc123"

project_name

string

The name of the project. The name of the project.

Example:

"My Scale Project"

batch_id

string

Scale's unique identifier for the batch. A unique identifier for the batch.

Example:

"batch_abc123"

batch_name

string

The name of the batch. 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. 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. 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. 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. 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. Entities that can be expanded from an ID to an object.

Entities that can be expanded from an ID to an object.

Available options:

project,

batch

opts

enum<string>[]

List of properties to include in the task response. Additional properties that can be included in the annotations

Property that can be included in the annotations

Available options:

annotation_details,

attachment_details,

model_parameters

Response

List of completed tasks.

tasks

object[]

required

Array of task objects

Show child attributes

tasks.task_id

string

required

Unique identifier for the task.

Example:

"task_abc123"

tasks.project

required

Project ID or Project associated with the task.

Example:

"project_abc123"

tasks.status

enum<string>

required

Current status of the task.

Available options:

pending,

completed,

canceled,

error

tasks.created_at

string<date-time>

required

UTC timestamp when the task was created.

tasks.batch

Batch ID or Batch associated with the task.

Example:

"batch_abc123"

tasks.completed_at

string<date-time>

UTC timestamp when the task was completed.

tasks.metadata

object

Custom metadata for the entity.

tasks.threads

object[]

Threads associated with the task. Tasks that do not have a status of completed will have an empty threads array.

Show child attributes

tasks.threads.id

string

required

Unique identifier for the thread.

Example:

"thread_abc123"

tasks.threads.turns

object[]

required

Turns within the thread.

Show child attributes

tasks.threads.turns.id

string

required

A unique identifier for the turn.

Example:

"turn_abc123"

tasks.threads.turns.messages

object[]

required

A list of messages associated with this turn.

Show child attributes

tasks.threads.turns.messages.role

enum<string>

required

The role of the sender in the conversation (e.g., user, assistant).

Available options:

system,

user,

assistant,

function

tasks.threads.turns.messages.content

object

required

The content of the message, including text and any attachments.

Show child attributes

tasks.threads.turns.messages.content.text

string

The textual content of the message.

tasks.threads.turns.messages.content.reference_texts

object[]

The reference texts associated with the message.

Show child attributes

tasks.threads.turns.messages.content.reference_texts.content

string

Content of the reference text.

tasks.threads.turns.messages.content.reference_texts.category

string

Category of the reference text.

tasks.threads.turns.messages.content.reference_texts.url

string

URL source of the reference text.

tasks.threads.turns.messages.content.attachments

(File · object | Detailed Image File · object | Detailed Audio File · object)[]

Any files or attachments included with the message.

File
Detailed Image File
Detailed Audio File

Show child attributes

tasks.threads.turns.messages.content.attachments.content

string<byte>

The base64-encoded content of the file.

tasks.threads.turns.messages.content.attachments.mime_type

string

The MIME type of the file, indicating its format.

Example:

"text/plain"

tasks.threads.turns.messages.content.attachments.scale_url

string

A URL pointing to the location of the file in Scale's storage.

tasks.threads.turns.messages.content.attachments.url

string

A URL pointing to the source location of the file.

tasks.threads.turns.messages.content.attachments.name

string

The name of the file.

tasks.threads.turns.messages.content.chunks

Text · object[]

Chunks specific to this message.

Show child attributes

tasks.threads.turns.messages.content.chunks.type

string

required

The type of chunked data.

tasks.threads.turns.messages.content.chunks.annotations

required

Annotations for a chunk of the message.

Represents a generic annotation.

Integer
Boolean
Text
Category
Category-Multiple
File
Workspace Container
Ranked Choices
Ranked Groups

Show child attributes

tasks.threads.turns.messages.content.chunks.annotations.id

string

required

Unique identifier for the annotation.

Example:

"an_abc123efg456"

tasks.threads.turns.messages.content.chunks.annotations.key

string

required

Key for the annotation.

Example:

"formatting"

tasks.threads.turns.messages.content.chunks.annotations.type

string

required

The type of the value and the possible_values, if they exist.

tasks.threads.turns.messages.content.chunks.annotations.title

string

Title of the annotation.

Example:

"Response Formatting"

tasks.threads.turns.messages.content.chunks.annotations.description

string

Further details about the question.

Example:

"Does the response contain issues with formatting?"

tasks.threads.turns.messages.content.chunks.annotations.labels

string[]

String representation of the possible options.

A string representation of the annotation.

Example:

["Major Issues", "Minor Issues", "No Issues"]

tasks.threads.turns.messages.content.chunks.annotations.metadata

object

Show child attributes

tasks.threads.turns.messages.content.chunks.annotations.metadata.criteria

Unique identifier for an annotation.

Example:

"overall_quality"

tasks.threads.turns.messages.content.chunks.annotations.value

integer

Integer type annotation value.

Example:

3

tasks.threads.turns.messages.content.chunks.annotations.possible_values

integer[]

The possible values for this annotation.

Integer type annotation value.

tasks.threads.turns.messages.content.chunks.text

string

required

A plain text field.

tasks.threads.turns.messages.content.reasoning

object[]

List of reasoning blocks for a message.

Show child attributes

tasks.threads.turns.messages.content.reasoning.content

string

The reasoning for the content of a message.

tasks.threads.turns.messages.source_id

string

required

The ID of the source system or user that sent the message.

Example:

"source_abc123"

tasks.threads.turns.messages.annotations

required

Annotations specific to this message.

Represents a generic annotation.

Integer
Boolean
Text
Category
Category-Multiple
File
Workspace Container
Ranked Choices
Ranked Groups

Show child attributes

tasks.threads.turns.messages.annotations.id

string

required

Unique identifier for the annotation.

Example:

"an_abc123efg456"

tasks.threads.turns.messages.annotations.key

string

required

Key for the annotation.

Example:

"formatting"

tasks.threads.turns.messages.annotations.type

string

required

The type of the value and the possible_values, if they exist.

tasks.threads.turns.messages.annotations.title

string

Title of the annotation.

Example:

"Response Formatting"

tasks.threads.turns.messages.annotations.description

string

Further details about the question.

Example:

"Does the response contain issues with formatting?"

tasks.threads.turns.messages.annotations.labels

string[]

String representation of the possible options.

A string representation of the annotation.

Example:

["Major Issues", "Minor Issues", "No Issues"]

tasks.threads.turns.messages.annotations.metadata

object

Show child attributes

tasks.threads.turns.messages.annotations.metadata.criteria

Unique identifier for an annotation.

Example:

"overall_quality"

tasks.threads.turns.messages.annotations.value

integer

Integer type annotation value.

Example:

3

tasks.threads.turns.messages.annotations.possible_values

integer[]

The possible values for this annotation.

Integer type annotation value.

tasks.threads.turns.messages.model_parameters

object

Show child attributes

tasks.threads.turns.messages.model_parameters.model

string

The name of the model that generated the message.

Example:

"my-model-123"

tasks.threads.turns.messages.model_parameters.temperature

number

The temperature of the model that generated the message.

Example:

0.9

tasks.threads.turns.messages.model_parameters.max_completion_tokens

integer

The maximum number of tokens the model can generate.

Example:

1000

tasks.threads.turns.messages.model_parameters.top_p

number

The top-p value of the model that generated the message.

Example:

0.9

tasks.threads.turns.messages.model_parameters.top_k

integer

The top-k value of the model that generated the message.

Example:

4

tasks.threads.turns.annotations

required

Annotations applied to the entire turn.

Represents a generic annotation.

Integer
Boolean
Text
Category
Category-Multiple
File
Workspace Container
Ranked Choices
Ranked Groups

Show child attributes

tasks.threads.turns.annotations.id

string

required

Unique identifier for the annotation.

Example:

"an_abc123efg456"

tasks.threads.turns.annotations.key

string

required

Key for the annotation.

Example:

"formatting"

tasks.threads.turns.annotations.type

string

required

The type of the value and the possible_values, if they exist.

tasks.threads.turns.annotations.title

string

Title of the annotation.

Example:

"Response Formatting"

tasks.threads.turns.annotations.description

string

Further details about the question.

Example:

"Does the response contain issues with formatting?"

tasks.threads.turns.annotations.labels

string[]

String representation of the possible options.

A string representation of the annotation.

Example:

["Major Issues", "Minor Issues", "No Issues"]

tasks.threads.turns.annotations.metadata

object

Show child attributes

tasks.threads.turns.annotations.metadata.criteria

Unique identifier for an annotation.

Example:

"overall_quality"

tasks.threads.turns.annotations.value

integer

Integer type annotation value.

Example:

3

tasks.threads.turns.annotations.possible_values

integer[]

The possible values for this annotation.

Integer type annotation value.

tasks.threads.annotations

required

Annotations for the entire thread.

Represents a generic annotation.

Integer
Boolean
Text
Category
Category-Multiple
File
Workspace Container
Ranked Choices
Ranked Groups

Show child attributes

tasks.threads.annotations.id

string

required

Unique identifier for the annotation.

Example:

"an_abc123efg456"

tasks.threads.annotations.key

string

required

Key for the annotation.

Example:

"formatting"

tasks.threads.annotations.type

string

required

The type of the value and the possible_values, if they exist.

tasks.threads.annotations.title

string

Title of the annotation.

Example:

"Response Formatting"

tasks.threads.annotations.description

string

Further details about the question.

Example:

"Does the response contain issues with formatting?"

tasks.threads.annotations.labels

string[]

String representation of the possible options.

A string representation of the annotation.

Example:

["Major Issues", "Minor Issues", "No Issues"]

tasks.threads.annotations.metadata

object

Show child attributes

tasks.threads.annotations.metadata.criteria

Unique identifier for an annotation.

Example:

"overall_quality"

tasks.threads.annotations.value

integer

Integer type annotation value.

Example:

3

tasks.threads.annotations.possible_values

integer[]

The possible values for this annotation.

Integer type annotation value.

tasks.errors

object[]

Errors associated with the task. Available when the task status is error

Show child attributes

tasks.errors.type

enum<string>

Type of the error

Available options:

UNSUPPORTED_LANGUAGE,

LANGUAGE_MISMATCH,

PROMPT_LENGTH_EXCEEDED,

INVALID_CATEGORY,

PROMPT_INFEASIBLE

Example:

"UNSUPPORTED_LANGUAGE"

tasks.errors.message

string

Details of the error message. e.g. Locale is not supported

Example:

"The specified language or locale is not supported"

tasks.sensitive_content_reports

object[]

Reports of sensitive content within the task. Available when the task status is completed. threads will not exist when the task is reported.

Show child attributes

tasks.sensitive_content_reports.type

string

Example:

"violence"

tasks.sensitive_content_reports.message

string

Example:

"The prompt in the task promotes violence."

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

Get Started

API Reference

Project Archetypes

Endpoints

Required query parameters

Example Code

Authorizations

Query Parameters

Response

Get Started

API Reference

Project Archetypes

Endpoints

​Required query parameters

​Example Code

Authorizations

Query Parameters

Response

Required query parameters

Example Code