Listing All Jobs

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:

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

Batch API

Datasets API

Headers

Query Parameters

Response

Code Examples

Job Object Fields

Notes

Batch API

Datasets API

​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