> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genai.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Dataset Tasks in a Delivery

> Retrieve multiple [Dataset Tasks](/core-resources/dataset-task) from a [Delivery](/core-resources/dataset-delivery).

<Accordion title="Authentication" icon="key">
  Every request sent to Scale's API requires authentication. In short, your API Key is the Bearer token. See the [Authentication](/get-started/authentication) section for more details.
</Accordion>

<Accordion title="Pagination" icon="file-lines">
  <Note>Remember to handle pagination when downloading large sets of tasks.</Note>

  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.
</Accordion>

<Tip>
  ### 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.
</Tip>

### Example Code

<Accordion icon="code" title="Download All Tasks From A Delivery as JSONL">
  ```python theme={null}
  # 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')

  ```
</Accordion>


## OpenAPI

````yaml GET /v2/datasets/delivery
openapi: 3.1.0
info:
  title: GenAI API Spec
  description: 'Data Engine: Generative AI API Specification'
  version: 0.0.1
servers:
  - url: https://api.scale.com
security:
  - bearerAuth: []
  - basicAuth: []
paths:
  /v2/datasets/delivery:
    get:
      tags:
        - v2
      summary: Get Dataset Tasks in a Delivery
      description: >-
        Retrieve multiple [Dataset Tasks](/core-resources/dataset-task) from a
        [Delivery](/core-resources/dataset-delivery).
      operationId: getDatasetDelivery
      parameters:
        - $ref: '#/components/parameters/delivery_id'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/next_token'
        - $ref: '#/components/parameters/datasets_expand_task'
      responses:
        '200':
          description: List of delivered dataset tasks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDatasetDeliveryResponse'
              examples:
                Sample Dataset Delivery:
                  value:
                    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
        '500':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status_code:
                    type: number
                    example: 500
                  error:
                    type: string
                    example: An error has occurred.
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            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"
        - lang: python
          label: Python SDK
          source: |
            import scaleapi

            API_KEY = 'live_...'
            client = scaleapi.ScaleClient(API_KEY)

            DELIVERY_ID = 'delivery_abc123'
            response = client.v2.get_dataset_delivery(DELIVERY_ID)
            print(response.to_json())
        - lang: python
          label: Python
          source: |
            import requests

            API_KEY = 'live_...'
            DELIVERY_ID = 'delivery_abc123'

            response = requests.request(
              "GET",
              url="https://api.scale.com/v2/datasets/delivery",
              params={"delivery_id": DELIVERY_ID},
              headers={
                "Accept": "application/json",
                "Authorization": f"Bearer {API_KEY}",
              },
            )
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >
            const API_KEY = 'live_...';

            const DELIVERY_ID = 'delivery_abc123';


            const params = new URLSearchParams({ delivery_id: DELIVERY_ID });


            const response = await
            fetch('https://api.scale.com/v2/datasets/delivery?' +
            params.toString(), {
              method: 'GET',
              headers: {
                'Accept': 'application/json',
                'Authorization': `Bearer ${API_KEY}`,
              },
            });

            console.log(await response.json());
        - lang: go
          label: Go
          source: |
            package main

            import (
              "fmt"
              "net/http"
              "io/ioutil"
            )

            func main() {
              apiKey := "live_..."
              deliveryId := "delivery_abc123"

              url := fmt.Sprintf("https://api.scale.com/v2/datasets/delivery?delivery_id=%s", deliveryId)

              req, _ := http.NewRequest("GET", url, nil)

              req.Header.Add("Accept", "application/json")
              req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey))

              res, _ := http.DefaultClient.Do(req)

              defer res.Body.Close()
              body, _ := ioutil.ReadAll(res.Body)

              fmt.Println(string(body))
            }
        - lang: java
          label: Java
          source: |
            import com.mashape.unirest.http.*;
            import com.mashape.unirest.http.exceptions.*;

            public class Main {
                public static void main(String[] args) throws UnirestException {
                    String apiKey = "live_...";
                    String deliveryId = "delivery_abc123";

                    String url = String.format("https://api.scale.com/v2/datasets/delivery?delivery_id=%s", deliveryId);

                    HttpResponse<String> response = Unirest.get(url)
                      .header("Accept", "application/json")
                      .header("Authorization", String.format("Bearer %s", apiKey))
                      .asString();

                    System.out.println(response.getBody());
                }
            }
components:
  parameters:
    delivery_id:
      name: delivery_id
      in: query
      required: false
      description: Scale's unique identifier for the delivery.
      schema:
        $ref: '#/components/schemas/DeliveryId'
    limit:
      name: limit
      in: query
      required: false
      description: Limit the number of entities returned.
      schema:
        $ref: '#/components/schemas/Limit'
    next_token:
      name: next_token
      in: query
      required: false
      description: >-
        A token used to retrieve the next page of results if there are more. You
        can find the `next_token` in your last request.
      schema:
        $ref: '#/components/schemas/NextToken'
    datasets_expand_task:
      name: expand
      in: query
      required: false
      description: >-
        List of fields to [expand](/api-reference/expanding-entities) in the
        response.
      schema:
        $ref: '#/components/schemas/ExpandDatasetTask'
  schemas:
    GetDatasetDeliveryResponse:
      type: object
      required:
        - tasks
      properties:
        delivery:
          $ref: '#/components/schemas/ExpandableDatasetDelivery'
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/DatasetTask'
        next_token:
          $ref: '#/components/schemas/NextToken'
    DeliveryId:
      type: string
      description: A unique identifier for the delivery.
      example: delivery_abc123
    Limit:
      type: integer
      minimum: 1
      maximum: 100
    NextToken:
      type: string
      description: >-
        A token used to retrieve the next page of results if there are more. You
        can find the `next_token` in your last request
    ExpandDatasetTask:
      type: array
      description: >-
        List of fields to [expand](/api-reference/expanding-entities) in the
        response.
      items:
        $ref: '#/components/schemas/ExpandableEnumDatasetTask'
    ExpandableDatasetDelivery:
      description: >-
        Delivery ID or [Delivery](/core-resources/dataset-delivery) associated
        with the task.
      oneOf:
        - $ref: '#/components/schemas/DatasetDeliveryId'
        - $ref: '#/components/schemas/DatasetDelivery'
    DatasetTask:
      type: object
      required:
        - task_id
        - dataset
        - delivery
        - response
      properties:
        task_id:
          $ref: '#/components/schemas/TaskId'
          description: Unique identifier for the task.
        dataset:
          $ref: '#/components/schemas/ExpandableDataset'
          description: >-
            Dataset ID or [Dataset](/core-resources/dataset) associated with the
            task.
        delivery:
          $ref: '#/components/schemas/ExpandableDatasetDelivery'
          description: >-
            Delivery ID or [Delivery](/core-resources/dataset-delivery)
            associated with the task.
        response:
          $ref: '#/components/schemas/DatasetResponse'
    ExpandableEnumDatasetTask:
      type: string
      description: Entities that can be expanded from an ID to an object.
      enum:
        - dataset
        - delivery
    DatasetDeliveryId:
      type: string
      description: Unique identifier for a delivery
      example: delivery_abc123
    DatasetDelivery:
      type: object
      required:
        - id
        - name
        - delivered_at
        - metadata
      properties:
        id:
          $ref: '#/components/schemas/DatasetDeliveryId'
        name:
          type: string
          description: The name of the delivery
          example: My Delivery - 2024-01-15
        delivered_at:
          $ref: '#/components/schemas/DateString'
          description: UTC timestamp when the delivery was created.
        dataset:
          $ref: '#/components/schemas/ExpandableDataset'
        metadata:
          $ref: '#/components/schemas/DatasetDeliveryMetadata'
    TaskId:
      type: string
      description: Unique identifier for a task
      example: task_abc123
    ExpandableDataset:
      description: >-
        Dataset ID or [Dataset](/core-resources/dataset) associated with the
        task.
      oneOf:
        - $ref: '#/components/schemas/DatasetId'
        - $ref: '#/components/schemas/Dataset'
    DatasetResponse:
      type: object
      description: Response associated with the dataset task.
      additionalProperties: true
    DateString:
      type: string
      format: date-time
      description: A timestamp formatted as an ISO 8601 date-time string.
    DatasetDeliveryMetadata:
      type: object
      properties:
        task_count:
          type: integer
          description: The number of tasks in the delivery
          example: 1000
        turn_count:
          type: integer
          description: The number of turns in the delivery
          example: 1000
    DatasetId:
      type: string
      description: Unique identifier for a dataset
      example: dataset_abc123
    Dataset:
      type: object
      required:
        - id
        - name
      properties:
        id:
          $ref: '#/components/schemas/DatasetId'
        name:
          $ref: '#/components/schemas/DatasetName'
    DatasetName:
      type: string
      description: The name of the dataset
      example: My Scale Dataset
  securitySchemes:
    bearerAuth:
      description: >-
        Your API Key is the Bearer token. See the
        [Authentication](/get-started/authentication) section to learn how to
        access your key.
      type: http
      scheme: bearer
    basicAuth:
      description: >-
        Basic HTTP Authentication. Your API Key is your username.  Learn more
        about setting up Authentication [here](/get-started/authentication).
      type: http
      scheme: basic

````