> ## 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.
# Listing All Jobs
> List all current and historical jobs with optional pagination
Using the API directly is not recommended for most users. Instead, we recommend using the [Python
SDK](/python-sdk/setup).
List all current and historical jobs with optional pagination support for handling large datasets efficiently.
## Headers
Your Sutro API key using Key authentication scheme.
Format: `Key YOUR_API_KEY`
Example: `Authorization: Key sk_live_abc123...`
## Query Parameters
Number of jobs to return per page. When provided, enables pagination.
* Minimum: 1
* Maximum: 100
* If omitted, returns all jobs without pagination
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)
Success message indicating jobs were retrieved
Complete list of all jobs for your account
### With Pagination (`limit` parameter provided)
List of jobs for the current page (up to `limit` items)
Cursor to fetch the next page of results. Will be `null` if there are no more pages.
```json Without Pagination theme={null}
{
"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"
}
]
}
```
```json With Pagination theme={null}
{
"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
```python Python - All Jobs theme={null}
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']}")
```
```python Python - Paginated theme={null}
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
```
```curl cURL - With Pagination theme={null}
# 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