Handle Pending Analysis

Overview

halal.sh covers a large but finite universe of instruments, and coverage grows over time. When you request /compliance for an instrument that hasn’t been analysed yet, the API doesn’t fail and it doesn’t queue work on demand — it returns a well-formed payload with determination.status: "pending" and the analysis fields left null. This guide shows how to detect that state and handle it gracefully.

All 12 sandbox instruments are already analysed, so you won’t see a pending status while testing against the sandbox key. The handling below matters once you’re live against the full universe.

What a pending response looks like

A pending instrument returns status: "pending" with every analysis field null — screens, revenue, purification, stability, and filing:

{
  "data": {
    "symbol": "EXMPL",
    "determination": { "status": "pending" },
    "screens": null,
    "revenue": null,
    "purification": null,
    "stability": null,
    "filing": null
  }
}

There is no auto-queue and no retry_after on a pending response. Re-requesting the same symbol in a loop won’t trigger analysis or change the result — it just burns rate limit. (The only place retry_after appears is on 429 rate-limit errors, which is unrelated to pending coverage.)

Detect pending

Branch on determination.status and treat pending as “compliance unknown” rather than an error.

Node.js
Python
React

async function getCompliance(symbol: string) {
  const res = await fetch(
    `https://api.halal.sh/v1/instruments/${symbol}/compliance`,
    { headers: { "X-API-Key": process.env.HALALSH_API_KEY } }
  );
  const { data } = await res.json();

  if (data.determination.status === "pending") {
    // Not analysed yet — screens/revenue/etc. are all null.
    return { symbol, status: "pending" };
  }

  return { symbol, status: data.determination.status, screens: data.screens };
}

import os
import requests

def get_compliance(symbol: str) -> dict:
    res = requests.get(
        f"https://api.halal.sh/v1/instruments/{symbol}/compliance",
        headers={"X-API-Key": os.environ["HALALSH_API_KEY"]},
    )
    data = res.json()["data"]

    if data["determination"]["status"] == "pending":
        # Not analysed yet — screens/revenue/etc. are all None.
        return {"symbol": symbol, "status": "pending"}

    return {"symbol": symbol, "status": data["determination"]["status"], "screens": data["screens"]}

function StockCompliance({ symbol }) {
  const [data, setData] = useState(null);

  useEffect(() => {
    // Calls your backend proxy, which holds the API key.
    fetch(`/api/compliance/${symbol}`)
      .then((res) => res.json())
      .then(({ data }) => setData(data));
  }, [symbol]);

  if (!data) return null;

  const { status } = data.determination;

  if (status === "pending") {
    return <span className="text-gray-500">Compliance not yet available</span>;
  }

  return <span>Status: {status}</span>;
}

Pending in a portfolio screen

POST /screen can return compliance_status: "pending" for any symbol that isn’t analysed yet. Partition the results and decide what each bucket means for your UI.

const { data } = await screen(symbols);

const compliant = data.filter((r) => r.compliance_status === "compliant");
const nonCompliant = data.filter((r) => r.compliance_status === "non-compliant");
const pending = data.filter((r) => r.compliance_status === "pending");

// `pending` symbols have no screens yet — surface them as "unknown",
// don't count them as either compliant or non-compliant.

What to show users

Status	Suggested UX
`compliant`	Compliant badge; optionally show the three screens
`non-compliant`	Non-compliant badge; show which screen failed
`pending`	Neutral “not yet analysed” state — never imply pass or fail

How coverage grows

Coverage expands as new instruments are analysed, so a symbol that’s pending today may return a full result later. Design for it: cache results you’ve already fetched, re-check pending symbols on a sensible cadence (for example, the next time a user opens that stock), and always render a clear neutral state in the meantime. Never block a screen or treat pending as a hard error.

Getting Started

Core Concepts

Guides

Handle Pending Analysis

Overview

What a pending response looks like

Detect pending

Pending in a portfolio screen

What to show users

How coverage grows

​Overview

​What a pending response looks like

​Detect pending

​Pending in a portfolio screen

​What to show users

​How coverage grows

Overview

What a pending response looks like

Detect pending

Pending in a portfolio screen

What to show users

How coverage grows