---
title: "Screen Bulk"
method: POST
path: "/api/screen-bulk"
tags: ["screening"]
---

# Screen Bulk

`POST /api/screen-bulk`

## Request

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

Trigger a new bulk Shariah screening run.

Starts asynchronous screening of all tickers in the specified index
(e.g. "SP500", "DJIA"). Returns immediately with a run ID that can be
used to poll status, fetch results, or cancel the run.

**curl example:**
```bash
curl -X POST "https://api.halalterminal.com/api/screen-bulk" \
     -H "X-API-Key: <API_KEY>" \
     -H "Content-Type: application/json" \
     -d '{"index_name": "SP500", "limit": 50, "force_refresh": false}'
```

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

resp = requests.post(
    "https://api.halalterminal.com/api/screen-bulk",
    headers={"X-API-Key": "<API_KEY>"},
    json={"index_name": "SP500", "limit": 50, "force_refresh": False},
)
print(resp.json())
```

## Request body

- BulkScreenRequest
  - `index_name` string, required: Name of the stock index to screen, e.g. 'SP500', 'DJIA'
  - `limit` integer, nullable: Maximum number of tickers to screen (None = all)
  - `force_refresh` boolean: Re-screen symbols even if cached results exist

## Response `202`

Bulk screening run accepted and queued

- BulkScreenResponse
  - `run_id` string, required
  - `index_name` string, required: Name of the index being screened, e.g. 'SP500'
  - `total` integer, required: Total number of tickers queued for screening
  - `tickers` string[], required: List of ticker symbols included in this run
  - `status` string
  - `created_at` string, nullable
  - `message` string, nullable
  - `count` integer, nullable
  - `queue_job_id` string, nullable

## Other responses

- `400`: Invalid request parameters
- `401`: API key required or invalid
- `422`: Validation Error
- `429`: Quota exceeded
- `500`: Internal server error

---

[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)