Get Started
API Reference
Project Archetypes
- Introduction
- Archetypes
Endpoints
- v2
- Tasks
- Deliveries
- Annotations
- v1
Get Multiple 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.
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_idorproject_name) - Batch (
batch_idorbatch_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
Your API Key is the Bearer token. See the Authentication section to learn how to access your key.
Query Parameters
Scale's unique identifier for the project.
The name of the project.
Scale's unique identifier for the batch.
The name of the batch.
The current status of the task, indicating whether it is pending, completed, error, or canceled.
pending, completed, canceled, error Tasks with a completed_at after the given date will be returned. A timestamp formatted as an ISO 8601 date-time string.
Tasks with a completed_at before the given date will be returned. A timestamp formatted as an ISO 8601 date-time string.
Limit the number of entities returned.
1 < x < 100A token used to retrieve the next page of results if there are more. You can find the next_token in your last request.
List of fields to expand in the response.
Entities that can be expanded from an ID to an object.
project, batch List of properties to include in the task response.
Property that can be included in the annotations
attachment_details, model_parameters Response
Array of task objects
Represents a single task
Unique identifier for the task.
Current status of the task.
pending, completed, canceled, error UTC timestamp when the task was created.
UTC timestamp when the task was completed.
Task metadata defined during task creation.
Threads associated with the task. Tasks that do not have a status of completed will have an empty threads array.
Represents a thread of messages in a task.
Unique identifier for the thread.
Turns within the thread.
A unique identifier for the turn.
A list of messages associated with this turn.
The role of the sender in the conversation (e.g., user, assistant).
system, user, assistant, function The content of the message, including text and any attachments.
The ID of the source system or user that sent the message.
Annotations specific to this message.
Represents a generic annotation.
Annotations applied to the entire turn.
Represents a generic annotation.
Unique identifier for the annotation.
Key for the annotation.
The type of the value and the possible_values, if they exist.
Title of the annotation.
Further details about the question.
String representation of the possible options.
A string representation of the annotation.
Integer type annotation value.
The possible values for this annotation.
Integer type annotation value.
Annotations for the entire thread.
Represents a generic annotation.
Unique identifier for the annotation.
Key for the annotation.
The type of the value and the possible_values, if they exist.
Title of the annotation.
Further details about the question.
String representation of the possible options.
A string representation of the annotation.
Unique identifier for an annotation.
Integer type annotation value.
The possible values for this annotation.
Integer type annotation value.
Errors associated with the task. Available when the task status is error
Details of the error on the task. Available when the task status is error
A token used to retrieve the next page of results if there are more. You can find the next_token in your last request
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"
}