Get Started
Project Archetypes
curl --request GET \
--url https://api.scale.com/v2/delivery \
--header 'Authorization: Bearer <token>'{
"tasks": [
{
"task_id": "task_abc123",
"project": "project_abc123",
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"batch": "batch_abc123",
"completed_at": "2023-11-07T05:31:56Z",
"metadata": {},
"threads": [
{
"id": "thread_abc123",
"turns": [
{
"id": "turn_abc123",
"messages": [
{
"role": "system",
"content": {
"text": "<string>",
"reference_texts": [
{
"content": "<string>",
"category": "<string>",
"url": "<string>"
}
],
"attachments": [
{
"content": "aSDinaTvuI8gbWludGxpZnk=",
"mime_type": "text/plain",
"scale_url": "<string>",
"url": "<string>",
"name": "<string>"
}
],
"chunks": [
{
"type": "<string>",
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
],
"text": "<string>"
}
],
"reasoning": [
{
"content": "<string>"
}
]
},
"source_id": "source_abc123",
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
],
"model_parameters": {
"model": "my-model-123",
"temperature": 0.9,
"max_completion_tokens": 1000,
"top_p": 0.9,
"top_k": 4
}
}
],
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
]
}
],
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
]
}
],
"errors": [
{
"type": "UNSUPPORTED_LANGUAGE",
"message": "The specified language or locale is not supported"
}
],
"sensitive_content_reports": [
{
"type": "violence",
"message": "The prompt in the task promotes violence."
}
]
}
],
"delivery": {
"id": "delivery_abc123",
"name": "My Scale Delivery",
"task_count": 1000,
"delivered_at": "2023-11-07T05:31:56Z",
"project": "project_abc123"
},
"next_token": "<string>"
}Get Tasks in a Delivery
curl --request GET \
--url https://api.scale.com/v2/delivery \
--header 'Authorization: Bearer <token>'{
"tasks": [
{
"task_id": "task_abc123",
"project": "project_abc123",
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"batch": "batch_abc123",
"completed_at": "2023-11-07T05:31:56Z",
"metadata": {},
"threads": [
{
"id": "thread_abc123",
"turns": [
{
"id": "turn_abc123",
"messages": [
{
"role": "system",
"content": {
"text": "<string>",
"reference_texts": [
{
"content": "<string>",
"category": "<string>",
"url": "<string>"
}
],
"attachments": [
{
"content": "aSDinaTvuI8gbWludGxpZnk=",
"mime_type": "text/plain",
"scale_url": "<string>",
"url": "<string>",
"name": "<string>"
}
],
"chunks": [
{
"type": "<string>",
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
],
"text": "<string>"
}
],
"reasoning": [
{
"content": "<string>"
}
]
},
"source_id": "source_abc123",
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
],
"model_parameters": {
"model": "my-model-123",
"temperature": 0.9,
"max_completion_tokens": 1000,
"top_p": 0.9,
"top_k": 4
}
}
],
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
]
}
],
"annotations": [
{
"id": "an_abc123efg456",
"key": "formatting",
"type": "<string>",
"title": "Response Formatting",
"description": "Does the response contain issues with formatting?",
"labels": [
"Major Issues",
"Minor Issues",
"No Issues"
],
"metadata": {
"criteria": "overall_quality"
},
"value": 3,
"possible_values": [
[
1,
2,
3
]
]
}
]
}
],
"errors": [
{
"type": "UNSUPPORTED_LANGUAGE",
"message": "The specified language or locale is not supported"
}
],
"sensitive_content_reports": [
{
"type": "violence",
"message": "The prompt in the task promotes violence."
}
]
}
],
"delivery": {
"id": "delivery_abc123",
"name": "My Scale Delivery",
"task_count": 1000,
"delivered_at": "2023-11-07T05:31:56Z",
"project": "project_abc123"
},
"next_token": "<string>"
}Authentication
Authentication
Pagination
Pagination
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 find a delivery:delivery_idDelivery IDs are globally unique and can be used to retrieve a specific delivery.delivery_namewith a project identifier (project_idorproject_name)
Example Code
Download All Tasks From A Delivery as JSONL
Download All Tasks From A Delivery as JSONL
# Downloads all tasks from a delivery
import json
import requests
API_KEY = 'live_...'
PROJECT_NAME = 'My Test Project'
DELIVERY_NAME = 'My Test Delivery'
def get_tasks_by_delivery(project_name: str, delivery_name: str):
tasks = []
params = {
"project_name": project_name,
"delivery_name": delivery_name,
}
should_fetch = True
while should_fetch:
response = requests.request(
"GET",
url="https://api.scale.com/v2/delivery",
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_delivery(PROJECT_NAME, DELIVERY_NAME)
with open(f'{DELIVERY_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 delivery. A unique identifier for the delivery.
"delivery_abc123"
The name of the delivery.
"My Scale Delivery"
Scale's unique identifier for the project. A unique identifier for the project.
"project_abc123"
The name of the project.
"My Scale Project"
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 properties to include in the task response. Additional properties that can be included in the annotations
Property that can be included in the annotations
annotation_details, attachment_details, model_parameters Response
List of delivered tasks.
Array of task objects
Show child attributes
Show child attributes
Unique identifier for the task.
"task_abc123"
Current status of the task.
pending, completed, canceled, error UTC timestamp when the task was created.
UTC timestamp when the task was completed.
Custom metadata for the entity.
Threads associated with the task. Tasks that do not have a status of completed will have an empty threads array.
Show child attributes
Show child attributes
Unique identifier for the thread.
"thread_abc123"
Turns within the thread.
Show child attributes
Show child attributes
A unique identifier for the turn.
"turn_abc123"
A list of messages associated with this turn.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
The textual content of the message.
The reference texts associated with the message.
Show child attributes
Show child attributes
Any files or attachments included with the message.
- File
- Detailed Image File
- Detailed Audio File
Show child attributes
Show child attributes
The base64-encoded content of the file.
The MIME type of the file, indicating its format.
"text/plain"
A URL pointing to the location of the file in Scale's storage.
A URL pointing to the source location of the file.
The name of the file.
Chunks specific to this message.
Show child attributes
Show child attributes
The type of chunked data.
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
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
A plain text field.
The ID of the source system or user that sent the message.
"source_abc123"
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
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
Show child attributes
Show child attributes
The name of the model that generated the message.
"my-model-123"
The temperature of the model that generated the message.
0.9
The maximum number of tokens the model can generate.
1000
The top-p value of the model that generated the message.
0.9
The top-k value of the model that generated the message.
4
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
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
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
Show child attributes
Unique identifier for the annotation.
"an_abc123efg456"
Key for the annotation.
"formatting"
The type of the value and the possible_values, if they exist.
Title of the annotation.
"Response Formatting"
Further details about the question.
"Does the response contain issues with formatting?"
String representation of the possible options.
A string representation of the annotation.
["Major Issues", "Minor Issues", "No Issues"]Integer type annotation value.
3
The possible values for this annotation.
Integer type annotation value.
Errors associated with the task. Available when the task status is error
Show child attributes
Show child attributes
Type of the error
UNSUPPORTED_LANGUAGE, LANGUAGE_MISMATCH, PROMPT_LENGTH_EXCEEDED, INVALID_CATEGORY, PROMPT_INFEASIBLE "UNSUPPORTED_LANGUAGE"
Details of the error message. e.g. Locale is not supported
"The specified language or locale is not supported"
Reports of sensitive content within the task. Available when the task status is completed. threads will not exist when the task is reported.
Delivery ID or Delivery associated with the task.
Show child attributes
Show child attributes
Unique identifier for the delivery.
"delivery_abc123"
The name of the delivery.
"My Scale Delivery"
The number of tasks in the delivery.
1000
UTC timestamp when the delivery was created.
A token used to retrieve the next page of results if there are more. You can find the next_token in your last request