Skip to main content
GET
/
list-jobs
Listing All Jobs
curl --request GET \
  --url https://api.sutro.sh/list-jobs \
  --header 'Authorization: <authorization>'
{
    "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"
        }
    ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.sutro.sh/llms.txt

Use this file to discover all available pages before exploring further.

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

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

​
Query Parameters

​
limit
integer
Number of jobs to return per page. When provided, enables pagination.
  • Minimum: 1
  • Maximum: 100
  • If omitted, returns all jobs without pagination
​
cursor
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)

​
message
string
Success message indicating jobs were retrieved
​
jobs
array
Complete list of all jobs for your account

​
With Pagination (limit parameter provided)

​
jobs
array
List of jobs for the current page (up to limit items)
​
next_cursor
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"
        }
    ]
}

​
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']}")

​
Job Object Fields

Each job in the jobs array contains the following fields:
FieldTypeDescription
job_idstringPublic identifier for the job
statusstringCurrent status of the job (SUCCEEDED, FAILED, RUNNING, PENDING, etc.)
modelstringThe model used for the job
system_promptstring | nullSystem prompt used for the job
job_priorityintegerPriority level of the job (0 or 1)
datetime_createdstringISO timestamp of when the job was created
datetime_startedstring | nullISO timestamp of when processing began
datetime_completedstring | nullISO timestamp of when the job completed
json_schemaobject | nullJSON schema for structured output (if used)
sampling_paramsobjectSampling parameters used for generation
namestring | nullOptional name for the job
descriptionstring | nullOptional description of the job
dataset_idstring | nullAssociated dataset identifier
input_tokensinteger | nullTotal input tokens processed
output_tokensinteger | nullTotal output tokens generated
job_costnumber | nullActual cost of the job in USD
num_rowsinteger | nullNumber of rows processed
failure_reasonobject | nullDetails if the job failed
cost_estimatenumber | nullEstimated 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