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

# Screen Bulk

`POST /api/etf/screen-bulk`

## Request

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

Screen multiple ETFs for Shariah compliance in a single request.

Accepts up to 100 ETF symbols and returns each ETF's compliance status,
compliant/non-compliant weights, and purification rate. Also includes a
summary with total/compliant/non-compliant/error counts. Pass
`force_refresh=true` to bypass cached results — available only for
enterprise and internal plans; for other plans the flag is silently
treated as False.

**curl example:**

    curl -X POST "http://localhost:8000/api/etf/screen-bulk" \
         -H "Content-Type: application/json" \
         -d '{"symbols": ["VTI", "SPY", "SCHB"], "force_refresh": false}'

**Python requests example:**

```python
import requests
resp = requests.post(
    "http://localhost:8000/api/etf/screen-bulk",
    json={"symbols": ["VTI", "SPY", "SCHB"], "force_refresh": False},
)
data = resp.json()
print(f"Compliant: {data['summary']['compliant']}/{data['summary']['total']}")
```

## Request body

- ETFBulkScreenRequest: Request to screen multiple ETFs in one call.
  - `symbols` string[], required: List of 1-100 ETF ticker symbols to screen.
  - `force_refresh` boolean: When true, bypass cached screening results and re-screen from scratch.

## Response `200`

Bulk screening results with per-ETF statuses and aggregate summary.

- ETFBulkScreenResponse: Response for a bulk ETF screening operation.
  - `results` ETFBulkScreenItemResult[]: Per-ETF screening results.
    - `symbol` string, required: ETF ticker symbol.
    - `is_compliant` boolean, nullable: Whether the ETF is Shariah-compliant.
    - `compliance_status` string: Overall compliance status.
    - `compliant_weight` number, nullable: Summed weight of the compliant holdings, in percent.
    - `non_compliant_weight` number, nullable: Summed weight of the non-compliant holdings, in percent.
    - `purification_rate` number, nullable: Weighted-average purification rate in percent, over the compliant rated holdings only, the same basis as GET /api/etf/{symbol}/screening. The whole-fund figure is `etf_purification_rate` on POST /api/etf/{symbol}/purification and runs higher.
    - `error` string, nullable: Error message if screening failed for this ETF.
  - `summary` ETFBulkScreenSummary: Aggregate statistics across all ETFs in a bulk screening run.
    - `total` integer: Total number of ETFs screened.
    - `compliant` integer: Number of compliant ETFs.
    - `non_compliant` integer: Number of non-compliant ETFs.
    - `errors` integer: Number of ETFs that failed to screen.

## Other responses

- `422`: Validation Error
- `429`: Rate limit exceeded. Try again later.

---

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