Get Dataset Tasks in a Delivery

API_KEY='live_...'
DELIVERY_ID='delivery_abc123'
curl --request GET \
    --url "https://api.scale.com/v2/datasets/delivery?delivery_id=$DELIVERY_ID" \
    --header "Authorization: Bearer $API_KEY"

{
  "delivery": {
    "id": "delivery_abc123",
    "name": "My Delivery - 2024-01-15",
    "delivered_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "task_count": 100,
      "turn_count": 100
    },
    "dataset": "dataset_abc123"
  },
  "tasks": [
    {
      "$ref": "#/components/examples/SampleDatasetTask/value"
    }
  ],
  "next_token": "imatoken123"
}

{
  "status_code": 500,
  "error": "An error has occurred."
}

GET

datasets

delivery

API_KEY='live_...'
DELIVERY_ID='delivery_abc123'
curl --request GET \
    --url "https://api.scale.com/v2/datasets/delivery?delivery_id=$DELIVERY_ID" \
    --header "Authorization: Bearer $API_KEY"

{
  "delivery": {
    "id": "delivery_abc123",
    "name": "My Delivery - 2024-01-15",
    "delivered_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "task_count": 100,
      "turn_count": 100
    },
    "dataset": "dataset_abc123"
  },
  "tasks": [
    {
      "$ref": "#/components/examples/SampleDatasetTask/value"
    }
  ],
  "next_token": "imatoken123"
}

{
  "status_code": 500,
  "error": "An error has occurred."
}

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 the following to find a delivery:

delivery_id Delivery IDs are globally unique and can be used to retrieve a specific delivery.

Example Code

Download All Tasks From A Delivery as JSONL

# Downloads all tasks from a delivery
import json
import requests


API_KEY = 'live_...'
delivery_id = 'delivery_123'

def get_tasks_by_delivery(delivery_id: str):
    tasks = []
    params = {
        "delivery_id": delivery_id,
    }

    should_fetch = True

    while should_fetch:
        response = requests.request(
            "GET",
            url="https://api.scale.com/v2/datasets/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(delivery_id)

    with open(f'{delivery_id}.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

delivery_id

string

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

Example:

"delivery_abc123"

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.

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

Available options:

dataset,

delivery

Response

List of delivered dataset tasks.

tasks

object[]

required

Show child attributes

delivery

Delivery ID or Delivery associated with the task.

Example:

"delivery_abc123"

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 Response Attachment List All Dataset Deliveries

⌘I

Get Started

API Reference

Project Archetypes

Endpoints

Get Dataset Tasks in a Delivery

Required query parameters

Example Code

Authorizations

Query Parameters

Response

​Required query parameters

​Example Code

Authorizations

Query Parameters

Response

Required query parameters

Example Code