> For a complete page index of the Captain API documentation, fetch https://docs.filesearch.dev/llms.txt?excludeSpec=true

# List Jobs

GET https://api.filesearch.dev/v2/jobs

List your indexing jobs, newest first. Filter by status or collection, and page through results with limit and offset. Use this to see what's currently running, review recent jobs, and check how many files each indexed. For the full detail of a single job, use GET /v2/jobs/\{job\_id}.

Reference: https://docs.filesearch.dev/reference/jobs/list

## Request

### Query parameters

- `status` (enum, optional, nullable) — Filter by job status.
  - Allowed values: `running`, `pending`, `processing`, `completed`, `completed_with_errors`, `failed`, `cancelled`, `timed_out`
- `collection` (string, optional, nullable) — Filter by collection name.
- `limit` (integer, optional, default: 50) — Jobs per page.
- `offset` (integer, optional, default: 0) — Pagination offset.

### Headers

- `authorization` (string, optional, nullable)

## Response

### 200

Successful Response

- `jobs` (list of JobSummaryV2, required)
- `total_count` (integer, required)
- `limit` (integer, required)
- `offset` (integer, required)

## Errors

### 400 Bad Request Error

Invalid status filter

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

### 401 Unauthorized Error

Missing or invalid API key

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

## Types

### JobSummaryV2

A single indexing job with its status and file counts.

- `job_id` (string, required)
- `status` (string, required) — running | pending | processing | completed | completed_with_errors | failed | cancelled | timed_out
- `job_type` (string, optional, nullable) — The indexing job type, e.g. index_s3, index_gcs_file, index_youtube.
- `storage_type` (string, optional, nullable)
- `collection_name` (string, optional, nullable)
- `environment` (string, optional, nullable) — The environment the job was submitted from: development, staging, or production.
- `job_name` (string, optional, nullable)
- `created_at` (string, optional, nullable)
- `finished_at` (string, optional, nullable)
- `files_total` (integer, optional, nullable)
- `files_indexed` (integer, optional, nullable)
- `files_failed` (integer, optional, nullable)
- `files_skipped` (integer, optional, nullable)
- `error` (string, optional, nullable)

### ErrorResponseV2Details

## Examples

**Response**

```json
{
  "jobs": [
    {
      "job_id": "job_s3_abc123",
      "status": "running",
      "job_type": "index_s3_directory",
      "storage_type": "s3",
      "collection_name": "my_documents",
      "environment": "production",
      "job_name": "Index s3://acme-docs/reports",
      "created_at": "2025-01-20T08:15:00Z",
      "finished_at": null,
      "files_total": 120,
      "files_indexed": 47,
      "files_failed": 0,
      "files_skipped": 3,
      "error": null
    }
  ],
  "total_count": 1,
  "limit": 50,
  "offset": 0
}
```

**SDK Code**

```python Python REST
import requests

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

response = requests.get(
    f"{BASE_URL}/v2/jobs",
    headers=headers,
    params={
        "status": "running",
        "limit": 50,
        "offset": 0
    },
    timeout=30.0
)

if response.status_code == 200:
    data = response.json()
    print(f"{data['total_count']} job(s)")
    for job in data.get("jobs") or []:
        print(f"  {job['job_id']} -> {job['status']} "
              f"(collection={job.get('collection_name')})")
else:
    print(f"Error: {response.status_code}")
```

```typescript TypeScript REST
const BASE_URL = "https://api.filesearch.dev";
const API_KEY = "your_api_key";

const query = new URLSearchParams({
    status: "running",
    limit: "50",
    offset: "0"
});

const response = await fetch(
    `${BASE_URL}/v2/jobs?${query}`,
    {
        headers: {
            "Authorization": `Bearer ${API_KEY}`
        }
    }
);

if (response.ok) {
    const data = await response.json();
    console.log(`${data.total_count} job(s)`);
    for (const job of data.jobs ?? []) {
        console.log(`  ${job.job_id} -> ${job.status} ` +
            `(collection=${job.collection_name})`);
    }
} else {
    console.error(`Error: ${response.status}`);
}
```