Handle pending analysis

Overview

When you request /compliance for an instrument we haven’t analyzed yet, the API returns a normal response with determination.status: "pending" and the analysis fields set to null. It doesn’t return an error, and reading it doesn’t start an analysis. On the Plus or Developer plan, you can request one.

All 12 sandbox instruments are analyzed, so no sandbox stock comes back pending. You’ll meet pending on a live key, against the full universe, and in an ETF’s holdings.

What a pending response looks like

A pending instrument has status: "pending" and every analysis field set to null: screens, revenue, purification, stability and filing.

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

A pending response doesn’t start an analysis and has no retry_after. Fetching the same symbol again in a loop won’t change the result, and every request counts against your rate limit. (retry_after appears only on 429 errors.)

Detect pending

Branch on determination.status, and treat pending as “not analyzed yet”, not as 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 analyzed yet: screens, revenue and the rest are 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 analyzed yet: screens, revenue and the rest are 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">Not analyzed yet</span>;
  }

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

Pending in a portfolio screen

POST /screen returns compliance_status: "pending" for any symbol we haven’t analyzed yet. Split the results by status:

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. Show them as not analyzed yet,
// and count them as neither compliant nor 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`	A neutral “Not analyzed yet” state that implies neither pass nor fail

Request an analysis

On the Plus or Developer plan, you can ask us to analyze a pending stock with POST /analysis-requests. If someone has already asked, you join that analysis instead of starting a second one. Poll the request until it’s complete, then read the result from /compliance:

const headers = { "X-API-Key": process.env.HALALSH_API_KEY, "Content-Type": "application/json" };

const created = await fetch("https://api.halal.sh/v1/analysis-requests", {
  method: "POST",
  headers,
  body: JSON.stringify({ symbol: "TYO:7203" }),
});
const { data: request } = await created.json();

// Later, every minute or two:
const res = await fetch(`https://api.halal.sh${request.links.self}`, { headers });
const { data } = await res.json();
if (data.status === "complete") {
  // data.determination is the published status; data.links.compliance has the full result.
}

Each new request counts against your account’s on-demand analysis allowance: 10 a day on the Plus and Developer plans, with up to 3 running at once. Add "notify": true to the request if you’d also like an email when we publish the result. The endpoint reference has the full list of refusals, such as a stock with no filings we can screen from.

When a pending symbol gets a result

A symbol that’s pending today may return a full result later, once we analyze it. Cache the results you’ve fetched, check pending symbols again from time to time (for example, the next time a user opens that stock), and show the neutral state until then. Don’t block a page on a pending symbol or treat pending as an 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

Request an analysis

When a pending symbol gets a result