---
title: "List Runs"
method: GET
path: "/api/screen-bulk/runs"
tags: ["screening"]
---

# List Runs

`GET /api/screen-bulk/runs`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/screen-bulk/runs`
- Auth: API key in header `X-API-Key`

List historical bulk screening runs.

Returns a paginated history of screening runs, optionally filtered by
index name (e.g. "SP500") or status (e.g. "completed", "running").

**curl example:**
```bash
curl -X GET "https://api.halalterminal.com/api/screen-bulk/runs?index_name=SP500&page=1&page_size=10" \
     -H "X-API-Key: <API_KEY>"
```

**Python requests example:**
```python
import requests

resp = requests.get(
    "https://api.halalterminal.com/api/screen-bulk/runs",
    params={"index_name": "SP500", "page": 1, "page_size": 10},
    headers={"X-API-Key": "<API_KEY>"},
)
print(resp.json())
```

## Query parameters

- `index_name` string, nullable: Filter runs by index name, e.g. SP500.
- `status` string, nullable: Filter runs by status, e.g. completed or running.
- `page` integer: Page number, 1-indexed.
- `page_size` integer: Number of runs per page.

## Response `200`

Paginated list of past and current screening runs

- RunHistoryResponse
  - `runs` RunHistoryItem[], required
    - `run_id` string, required
    - `index_name` string, required
    - `status` string, required
    - `total` integer, required
    - `done` integer, required
    - `failed_count` integer
    - `compliance_rate` number, nullable: Overall compliance rate for this run (available after completion)
    - `created_at` string, nullable
    - `finished_at` string, nullable
    - `duration_seconds` integer, nullable
  - `total_runs` integer, required
  - `page` integer, required
  - `page_size` integer, required

## Other responses

- `401`: API key required or invalid
- `422`: Validation Error
- `429`: Quota exceeded

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)