Listing All Jobs

curl --request GET \
  --url https://api.sutro.sh/list-jobs \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.sutro.sh/list-jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sutro.sh/list-jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sutro.sh/list-jobs"

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

	req.Header.Add("Authorization", "<authorization>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sutro.sh/list-jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
    "message": "Jobs retrieved successfully.",
    "jobs": [
        {
            "model": "llama-3.1-8b",
            "system_prompt": "You are a helpful assistant.",
            "job_priority": 1,
            "status": "succeeded",
            "datetime_created": "2024-01-15T10:30:00Z",
            "datetime_started": "2024-01-15T10:30:15Z",
            "datetime_completed": "2024-01-15T10:32:15Z",
            "json_schema": null,
            "sampling_params": {
            "temperature": 0.7,
            "top_p": 0.95,
            "max_tokens": 2048
        },
            "name": "Customer Support Batch",
            "description": "Processing customer inquiries",
            "dataset_id": "dataset_abc123",
            "input_tokens": 15420,
            "output_tokens": 8230,
            "job_cost": 0.0234,
            "num_rows": 50,
            "failure_reason": null,
            "cost_estimate": 0.025,
            "run_type": "FULL",
            "job_id": "batch_job_12345"
        }
    ]
}

{
    "jobs": [
        {
            "model": "llama-3.1-8b",
            "system_prompt": "You are a helpful assistant.",
            "job_priority": 1,
            "status": "succeeded",
            "datetime_created": "2024-01-15T10:30:00Z",
            "datetime_started": "2024-01-15T10:30:15Z",
            "datetime_completed": "2024-01-15T10:32:15Z",
            "json_schema": null,
            "sampling_params": {
            "temperature": 0.7,
            "top_p": 0.95,
            "max_tokens": 2048
        },
            "name": "Customer Support Batch",
            "description": "Processing customer inquiries",
            "dataset_id": "dataset_abc123",
            "input_tokens": 15420,
            "output_tokens": 8230,
            "job_cost": 0.0234,
            "num_rows": 50,
            "failure_reason": null,
            "cost_estimate": 0.025,
            "run_type": "FULL",
            "job_id": "batch_job_12345"
        }
    ],
    "next_cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiYmF0Y2hfam9iXzEyMzQ1In0="
}

GET

list-jobs

Listing All Jobs

curl --request GET \
  --url https://api.sutro.sh/list-jobs \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.sutro.sh/list-jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sutro.sh/list-jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.sutro.sh/list-jobs"

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

	req.Header.Add("Authorization", "<authorization>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sutro.sh/list-jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
    "message": "Jobs retrieved successfully.",
    "jobs": [
        {
            "model": "llama-3.1-8b",
            "system_prompt": "You are a helpful assistant.",
            "job_priority": 1,
            "status": "succeeded",
            "datetime_created": "2024-01-15T10:30:00Z",
            "datetime_started": "2024-01-15T10:30:15Z",
            "datetime_completed": "2024-01-15T10:32:15Z",
            "json_schema": null,
            "sampling_params": {
            "temperature": 0.7,
            "top_p": 0.95,
            "max_tokens": 2048
        },
            "name": "Customer Support Batch",
            "description": "Processing customer inquiries",
            "dataset_id": "dataset_abc123",
            "input_tokens": 15420,
            "output_tokens": 8230,
            "job_cost": 0.0234,
            "num_rows": 50,
            "failure_reason": null,
            "cost_estimate": 0.025,
            "run_type": "FULL",
            "job_id": "batch_job_12345"
        }
    ]
}

{
    "jobs": [
        {
            "model": "llama-3.1-8b",
            "system_prompt": "You are a helpful assistant.",
            "job_priority": 1,
            "status": "succeeded",
            "datetime_created": "2024-01-15T10:30:00Z",
            "datetime_started": "2024-01-15T10:30:15Z",
            "datetime_completed": "2024-01-15T10:32:15Z",
            "json_schema": null,
            "sampling_params": {
            "temperature": 0.7,
            "top_p": 0.95,
            "max_tokens": 2048
        },
            "name": "Customer Support Batch",
            "description": "Processing customer inquiries",
            "dataset_id": "dataset_abc123",
            "input_tokens": 15420,
            "output_tokens": 8230,
            "job_cost": 0.0234,
            "num_rows": 50,
            "failure_reason": null,
            "cost_estimate": 0.025,
            "run_type": "FULL",
            "job_id": "batch_job_12345"
        }
    ],
    "next_cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiYmF0Y2hfam9iXzEyMzQ1In0="
}

Using the API directly is not recommended for most users. Instead, we recommend using the Python SDK.

List all current and historical jobs with optional pagination support for handling large datasets efficiently.

Headers

string

required

Your Sutro API key using Key authentication scheme.Format: Key YOUR_API_KEYExample: Authorization: Key sk_live_abc123...

Query Parameters

integer

Number of jobs to return per page. When provided, enables pagination.

Minimum: 1
Maximum: 100
If omitted, returns all jobs without pagination

string

Opaque cursor string for pagination. Use the next_cursor value from the previous response to fetch the next page.Only used when limit is also provided.

Response

Returns a list of jobs associated with your account. The response structure varies based on whether pagination is used.

Without Pagination (no `limit` parameter)

string

Success message indicating jobs were retrieved

array

Complete list of all jobs for your account

With Pagination (`limit` parameter provided)

array

List of jobs for the current page (up to limit items)

string | null

Cursor to fetch the next page of results. Will be null if there are no more pages.

{
    "message": "Jobs retrieved successfully.",
    "jobs": [
        {
            "model": "llama-3.1-8b",
            "system_prompt": "You are a helpful assistant.",
            "job_priority": 1,
            "status": "succeeded",
            "datetime_created": "2024-01-15T10:30:00Z",
            "datetime_started": "2024-01-15T10:30:15Z",
            "datetime_completed": "2024-01-15T10:32:15Z",
            "json_schema": null,
            "sampling_params": {
            "temperature": 0.7,
            "top_p": 0.95,
            "max_tokens": 2048
        },
            "name": "Customer Support Batch",
            "description": "Processing customer inquiries",
            "dataset_id": "dataset_abc123",
            "input_tokens": 15420,
            "output_tokens": 8230,
            "job_cost": 0.0234,
            "num_rows": 50,
            "failure_reason": null,
            "cost_estimate": 0.025,
            "run_type": "FULL",
            "job_id": "batch_job_12345"
        }
    ]
}

{
    "jobs": [
        {
            "model": "llama-3.1-8b",
            "system_prompt": "You are a helpful assistant.",
            "job_priority": 1,
            "status": "succeeded",
            "datetime_created": "2024-01-15T10:30:00Z",
            "datetime_started": "2024-01-15T10:30:15Z",
            "datetime_completed": "2024-01-15T10:32:15Z",
            "json_schema": null,
            "sampling_params": {
            "temperature": 0.7,
            "top_p": 0.95,
            "max_tokens": 2048
        },
            "name": "Customer Support Batch",
            "description": "Processing customer inquiries",
            "dataset_id": "dataset_abc123",
            "input_tokens": 15420,
            "output_tokens": 8230,
            "job_cost": 0.0234,
            "num_rows": 50,
            "failure_reason": null,
            "cost_estimate": 0.025,
            "run_type": "FULL",
            "job_id": "batch_job_12345"
        }
    ],
    "next_cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiYmF0Y2hfam9iXzEyMzQ1In0="
}

Code Examples

import requests

response = requests.get(
    'https://api.sutro.sh/list-jobs',
    headers={
        'Authorization': 'Key YOUR_SUTRO_API_KEY'
    }
)

result = response.json()
print(f"Total jobs: {len(result['jobs'])}")

for job in result['jobs']:
    print(f"{job['job_id']}: {job['status']} - {job['model']}")

import requests

api_key = 'YOUR_SUTRO_API_KEY'
cursor = None
page_size = 50

# Process jobs page by page
while True:
    params = {'limit': page_size}
    if cursor:
        params['cursor'] = cursor

    response = requests.get(
        'https://api.sutro.sh/list-jobs',
        headers={'Authorization': f'Key {api_key}'},
        params=params
    )
    data = response.json()

    for job in data['jobs']:
        print(f"{job['job_id']}: {job['status']} - {job['model']}")

    cursor = data.get('next_cursor')
    if not cursor:
        break

# First page
curl -X GET "https://api.sutro.sh/list-jobs?limit=20" \
-H "Authorization: Key YOUR_SUTRO_API_KEY"

# Next page (using cursor from previous response)
curl -X GET "https://api.sutro.sh/list-jobs?limit=20&cursor=YOUR_CURSOR_HERE" \
-H "Authorization: Key YOUR_SUTRO_API_KEY"

Job Object Fields

Each job in the jobs array contains the following fields:

Field	Type	Description
`job_id`	string	Public identifier for the job
`status`	string	Current status of the job (SUCCEEDED, FAILED, RUNNING, PENDING, etc.)
`model`	string	The model used for the job
`system_prompt`	string \| null	System prompt used for the job
`job_priority`	integer	Priority level of the job (0 or 1)
`datetime_created`	string	ISO timestamp of when the job was created
`datetime_started`	string \| null	ISO timestamp of when processing began
`datetime_completed`	string \| null	ISO timestamp of when the job completed
`json_schema`	object \| null	JSON schema for structured output (if used)
`sampling_params`	object	Sampling parameters used for generation
`name`	string \| null	Optional name for the job
`description`	string \| null	Optional description of the job
`dataset_id`	string \| null	Associated dataset identifier
`input_tokens`	integer \| null	Total input tokens processed
`output_tokens`	integer \| null	Total output tokens generated
`job_cost`	number \| null	Actual cost of the job in USD
`num_rows`	integer \| null	Number of rows processed
`failure_reason`	object \| null	Details if the job failed
`cost_estimate`	number \| null	Estimated cost before processing

Notes

Jobs are returned in reverse chronological order (newest first)
When using pagination, the cursor is opaque and should not be modified
Use the limit parameter for better performance when dealing with large numbers of jobs

Functions API

Batch API

Listing All Jobs

Headers

Query Parameters

Response

Code Examples

Job Object Fields

Notes

​Headers

​Query Parameters

​Response

​Without Pagination (no limit parameter)

​With Pagination (limit parameter provided)

​Code Examples

​Job Object Fields

​Notes

Headers

Query Parameters

Response

Without Pagination (no `limit` parameter)

With Pagination (`limit` parameter provided)

Code Examples

Job Object Fields

Notes