> ## 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 Delivered Task Responses
> Retrieve delivered [Task](/core-resources/task) response data from a [Project](/core-resources/project), optionally filtered by [Delivery](/core-resources/delivery).
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.
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 must provide one of the following:
* `project_id` or `project_name` - Get all delivered tasks from a project
### Optional filters
* `delivery_id` - Filter to tasks from a specific delivery
* `status` - Filter by task status
* `completed_after`, `completed_before` - Filter by completion time range
## Overview
Returns delivered task responses from a project. For delivered tasks, includes:
* Complete response data (threads, turns, messages, annotations, etc.)
* Delivery timestamp and ID
* Task metadata
Tasks without deliveries have `null` for delivery-related fields.
**Compared to `/v2/delivery`:** Returns full task response content, not just task metadata.
## OpenAPI
````yaml GET /v2/delivery/tasks
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/delivery/tasks:
get:
tags:
- v2
summary: Get Delivered Task Responses
description: >
Retrieve delivered [Task](/core-resources/task) response data from a
[Project](/core-resources/project), optionally filtered by
[Delivery](/core-resources/delivery).
operationId: getDeliveryTasks
parameters:
- $ref: '#/components/parameters/delivery_id'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/project_name'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/completed_after'
- $ref: '#/components/parameters/completed_before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/next_token'
responses:
'200':
description: List of tasks with delivered responses.
content:
application/json:
schema:
$ref: '#/components/schemas/GetDeliveryTasksResponse'
examples:
Delivered Tasks:
value:
docs:
- task_id: task_abc123
delivery_id: delivery_xyz789
delivered_at: '2024-01-15T10:30:00Z'
response:
threads:
- id: thread_0
turns:
- id: turn_0
messages:
- role: user
content:
text: What is machine learning?
- role: assistant
content:
text: Machine learning is...
annotations:
- key: quality
value: 5
total: 1
next_token: eyJza2lwIjoxMDB9
Non-Delivered Tasks:
value:
docs:
- task_id: task_pending123
delivery_id: null
delivered_at: null
response: null
total: 1
next_token: null
'400':
description: Bad request - invalid parameters
content:
application/json:
schema:
type: object
properties:
status_code:
type: number
example: 400
error:
type: string
example: 'Invalid parameter: limit must be between 1 and 100'
'404':
description: Not found - specified delivery or project does not exist
content:
application/json:
schema:
type: object
properties:
status_code:
type: number
example: 404
error:
type: string
example: Delivery not found
'500':
description: Internal server error
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_...'
PROJECT_ID='project_abc123'
DELIVERY_ID='delivery_xyz789'
# Get all delivered tasks from a project
curl --request GET \
--url "https://api.scale.com/v2/delivery/tasks?project_id=$PROJECT_ID&limit=100" \
--header "Authorization: Bearer $API_KEY"
# Filter by specific delivery within a project
curl --request GET \
--url "https://api.scale.com/v2/delivery/tasks?project_id=$PROJECT_ID&delivery_id=$DELIVERY_ID&limit=100" \
--header "Authorization: Bearer $API_KEY"
# Filter by time range
curl --request GET \
--url "https://api.scale.com/v2/delivery/tasks?project_id=$PROJECT_ID&completed_after=2024-01-01T00:00:00Z&limit=50" \
--header "Authorization: Bearer $API_KEY"
- lang: python
label: Python SDK
source: |
import scaleapi
API_KEY = 'live_...'
client = scaleapi.ScaleClient(API_KEY)
PROJECT_ID = 'project_abc123'
response = client.v2.get_delivery_tasks(
project_id=PROJECT_ID,
limit=100
)
print(response.to_json())
# Filter by specific delivery
DELIVERY_ID = 'delivery_xyz789'
response = client.v2.get_delivery_tasks(
project_id=PROJECT_ID,
delivery_id=DELIVERY_ID,
limit=100
)
# Paginate through all results
next_token = response.get('next_token')
while next_token:
response = client.v2.get_delivery_tasks(
project_id=PROJECT_ID,
limit=100,
next_token=next_token
)
next_token = response.get('next_token')
- lang: python
label: Python
source: |
import requests
API_KEY = 'live_...'
PROJECT_ID = 'project_abc123'
# Get all delivered tasks from a project
response = requests.get(
url="https://api.scale.com/v2/delivery/tasks",
params={"project_id": PROJECT_ID, "limit": 100},
headers={
"Accept": "application/json",
"Authorization": f"Bearer {API_KEY}",
},
)
data = response.json()
print(f"Retrieved {data['total']} tasks")
# Filter by specific delivery
DELIVERY_ID = 'delivery_xyz789'
response = requests.get(
url="https://api.scale.com/v2/delivery/tasks",
params={"project_id": PROJECT_ID, "delivery_id": DELIVERY_ID, "limit": 100},
headers={
"Accept": "application/json",
"Authorization": f"Bearer {API_KEY}",
},
)
# Process delivered tasks
for task in data['docs']:
if task['delivery_id']:
print(f"Task {task['task_id']}: {task['response']}")
- lang: javascript
label: JavaScript
source: >
const API_KEY = 'live_...';
const PROJECT_ID = 'project_abc123';
// Get all delivered tasks from a project
let params = new URLSearchParams({
project_id: PROJECT_ID,
limit: '100'
});
let response = await
fetch('https://api.scale.com/v2/delivery/tasks?' +
params.toString(), {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: `Bearer ${API_KEY}`,
},
});
let data = await response.json();
console.log(`Retrieved ${data.total} tasks`);
// Filter by specific delivery
const DELIVERY_ID = 'delivery_xyz789';
params = new URLSearchParams({
project_id: PROJECT_ID,
delivery_id: DELIVERY_ID,
limit: '100'
});
response = await fetch('https://api.scale.com/v2/delivery/tasks?' +
params.toString(), {
headers: {
Accept: 'application/json',
Authorization: `Bearer ${API_KEY}`,
},
});
// Paginate through results
let nextToken = data.next_token;
while (nextToken) {
params = new URLSearchParams({
project_id: PROJECT_ID,
limit: '100',
next_token: nextToken
});
response = await fetch('https://api.scale.com/v2/delivery/tasks?' + params.toString(), {
headers: {
Accept: 'application/json',
Authorization: `Bearer ${API_KEY}`,
},
});
data = await response.json();
nextToken = data.next_token;
}
- lang: go
label: Go
source: |
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
func main() {
apiKey := "live_..."
projectID := "project_abc123"
// Get all delivered tasks from a project
params := url.Values{}
params.Add("project_id", projectID)
params.Add("limit", "100")
reqURL := fmt.Sprintf("https://api.scale.com/v2/delivery/tasks?%s", params.Encode())
req, _ := http.NewRequest("GET", reqURL, nil)
req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
var response map[string]interface{}
json.Unmarshal(body, &response)
fmt.Printf("Retrieved %v tasks\n", response["total"])
}
- lang: java
label: Java
source: |
package com.scale.api;
import kong.unirest.HttpResponse;
import kong.unirest.Unirest;
import kong.unirest.json.JSONObject;
public class App {
public static void main(String[] args) {
String apiKey = "live_...";
String projectId = "project_abc123";
// Get all delivered tasks from a project
String url = String.format(
"https://api.scale.com/v2/delivery/tasks?project_id=%s&limit=100",
projectId
);
HttpResponse response = Unirest.get(url)
.header("Authorization", String.format("Bearer %s", apiKey))
.asString();
JSONObject data = new JSONObject(response.getBody());
System.out.println(String.format("Retrieved %d tasks", data.getInt("total")));
}
}
components:
parameters:
delivery_id:
name: delivery_id
in: query
required: false
description: Scale's unique identifier for the delivery.
schema:
$ref: '#/components/schemas/DeliveryId'
project_id:
name: project_id
in: query
required: false
description: Scale's unique identifier for the project.
schema:
$ref: '#/components/schemas/ProjectId'
project_name:
name: project_name
in: query
required: false
description: The name of the project.
schema:
$ref: '#/components/schemas/ProjectName'
status:
name: status
in: query
required: false
description: >-
The current status of the task, indicating whether it is pending,
completed, error, or canceled.
schema:
$ref: '#/components/schemas/TaskStatus'
completed_after:
name: completed_after
in: query
required: false
description: >-
Tasks with a `completed_at` after the given date will be returned. A
timestamp formatted as an ISO 8601 date-time string.
schema:
$ref: '#/components/schemas/DateString'
completed_before:
name: completed_before
in: query
required: false
description: >-
Tasks with a `completed_at` before the given date will be returned. A
timestamp formatted as an ISO 8601 date-time string.
schema:
$ref: '#/components/schemas/DateString'
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'
schemas:
GetDeliveryTasksResponse:
type: object
required:
- docs
- total
properties:
docs:
type: array
items:
type: object
properties:
task_id:
type: string
description: Unique identifier for the task
delivery_id:
type: string
nullable: true
description: ID of the delivery this task was included in
delivered_at:
type: string
format: date-time
nullable: true
description: Timestamp when the task was delivered
response:
type: object
nullable: true
description: The delivered response data for this task
total:
type: integer
description: Total number of tasks returned
next_token:
type: string
description: Token for pagination to retrieve the next page of results
DeliveryId:
type: string
description: A unique identifier for the delivery.
example: delivery_abc123
ProjectId:
type: string
description: A unique identifier for the project.
example: project_abc123
ProjectName:
type: string
description: The name of the project.
example: My Scale Project
TaskStatus:
type: string
enum:
- pending
- completed
- canceled
- error
description: >-
The current status of the task, indicating whether it is pending,
completed, error, or canceled.
DateString:
type: string
format: date-time
description: A timestamp formatted as an ISO 8601 date-time string.
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
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
````