---
title: "Bulk Status"
method: GET
path: "/api/screen-bulk/status"
tags: ["screening"]
---

# Bulk Status

`GET /api/screen-bulk/status`

## Request

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

Get the status of a bulk screening run.

Returns real-time progress for the active run (or a specific run if
`run_id` is provided), including completion percentage, current symbol
being processed, and estimated time remaining.

**curl example:**
```bash
curl -X GET "https://api.halalterminal.com/api/screen-bulk/status?run_id=abc123" \
     -H "X-API-Key: <API_KEY>"
```

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

resp = requests.get(
    "https://api.halalterminal.com/api/screen-bulk/status",
    params={"run_id": "abc123"},
    headers={"X-API-Key": "<API_KEY>"},
)
print(resp.json())
```

## Query parameters

- `run_id` string, nullable: Specific run ID to check; defaults to the active or most recent run.

## Response `200`

Current status of the active or most recent bulk screening run

- BulkStatusResponse
  - `run_id` string, nullable
  - `running` boolean, required
  - `status` string, nullable: Run lifecycle status: pending, running, completed, cancelled, failed
  - `index_name` string, nullable
  - `total` integer
  - `done` integer
  - `failed_count` integer: Number of symbols that failed during screening
  - `current_symbol` string, nullable: Ticker currently being processed
  - `progress_pct` number: Completion percentage (0.0 to 100.0)
  - `estimated_remaining_seconds` integer, nullable
  - `created_at` string, nullable
  - `started_at` string, nullable
  - `updated_at` string, nullable
  - `finished_at` string, nullable
  - `last_error` string, nullable: Most recent error message, if any

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