Batch workflows

There is no bulk fundamentals endpoint — a factor batch is your own loop, one symbol per request. Use stock_universe to build the symbol set, fetch the overview for covered rows, and deepen only the shortlist. The rate you run at is set by your plan’s per-minute limit.

Resolve coverage before you spend the batch

stock_universe {"coverage":"has_fundamentals"} returns the symbols eligible for a fundamentals fan-out without one resolution call per ticker. Page with next_offset; use the shape filter when a factor only applies to a statement family. Use stock_search only for user-entered names/tickers, and stock_reference {"catalog":"coverage"} for measured aggregate rates.

Concurrency follows the minute limit

Pick your in-flight count from the plan’s per-minute limit and leave headroom for retries.

Plan	Minute limit	In-flight
Free	30 / min	1–2
Starter	60 / min	2–3
Builder	300 / min	5 or more

Also mind the quota: Free is 100 requests per day, which a single 30-symbol watchlist refresh can exhaust once you add a resolve call and an overview call each. Read X-Credits-Remaining after each authenticated tool call when it is present, and stop immediately on a quota_exhausted 429. See Plans and limits.

A bounded worker pool

Both versions cap in-flight requests and back off on a 429.

Python
TypeScript

batch.py

import asyncio
import httpx

BASE = "https://api.stockcontext.com"


async def overview(client, sem, symbol, key):
    async with sem:  # cap in-flight at the semaphore's size
        res = await client.post(
            f"{BASE}/v1/tools/stock_overview",
            json={"symbol": symbol},
            headers={"X-API-Key": key},
        )
        if res.status_code == 429:
            reason = None
            try:
                reason = res.json().get("reason")
            except ValueError:
                pass
            if reason == "quota_exhausted":
                remaining = res.headers.get("X-Credits-Remaining", "0")
                raise RuntimeError(f"quota exhausted; credits remaining: {remaining}")
            retry_after = float(res.headers.get("Retry-After", 5))
            await asyncio.sleep(retry_after)
            return await overview(client, sem, symbol, key)
        res.raise_for_status()
        return symbol, res.json()


async def run(symbols, key, in_flight=2):  # Free: 1–2, Builder: 5+
    sem = asyncio.Semaphore(in_flight)
    async with httpx.AsyncClient(timeout=15) as client:
        return await asyncio.gather(*(overview(client, sem, s, key) for s in symbols))

batch.ts

const BASE = "https://api.stockcontext.com";
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function overview(symbol: string, key: string): Promise<[string, unknown]> {
  const res = await fetch(`${BASE}/v1/tools/stock_overview`, {
    method: "POST",
    headers: { "X-API-Key": key, "Content-Type": "application/json" },
    body: JSON.stringify({ symbol }),
  });
  if (res.status === 429) {
    let reason: unknown;
    try {
      reason = (await res.clone().json()).reason;
    } catch {}
    if (reason === "quota_exhausted") {
      throw new Error(
        `quota exhausted; credits remaining: ${res.headers.get("X-Credits-Remaining") ?? "0"}`,
      );
    }
    const retryAfter = Number(res.headers.get("Retry-After") ?? 5);
    await sleep(retryAfter * 1000);
    return overview(symbol, key);
  }
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return [symbol, await res.json()];
}

// Plain promise pool, no dependency. Free: inFlight 1–2, Builder: 5+.
async function run(symbols: string[], key: string, inFlight = 2) {
  const queue = [...symbols];
  const results: [string, unknown][] = [];
  const workers = Array.from({ length: inFlight }, async () => {
    let symbol: string | undefined;
    while ((symbol = queue.shift())) results.push(await overview(symbol, key));
  });
  await Promise.all(workers);
  return results;
}

The typed reason separates a minute 429 from a quota 429; do not infer it from timing. For the full policy (attempt caps, total-wait budget), wrap each request with the loop in Errors and retries.

Watching for new data

Schema 2 successful 200 responses include a composite ETag. Store the response and send the same request body later with If-None-Match. A 304 Not Modified has an empty body and means your cached response is still current for that exact tool, schema, params, fundamentals build, policy version, and market cursor. For fundamentals, watch meta.as_of.sec, meta.published_at, meta.build.fundamentals, and meta.last_verified_at when present. For price-backed responses, also watch meta.as_of.market and the response freshness fields such as sessions_behind. Use this polling shape for watchlists:

Resolve the symbol once with stock_search.
Fetch schema 2 data and persist the body plus ETag.
Re-poll with the same body and If-None-Match.
On 304, reuse your cached body. On 200, replace it and store the new ETag.

Schema 2 304s still pass authentication and rate limiting, but the quota credit is refunded at the API edge. Do not expect a response body on 304.

Keep SEC-backed tools out of a tight loop

stock_filings, stock_insider, and stock_ownership read SEC data and can be slow cold, so pull them only for the shortlist a user actually opens — in a background job, cached hard.

Where batches go wrong

Fanning out stock_overview over symbols you never checked with stock_search, spending quota on ingestion_pending tickers.
Continuing to send after a 429 instead of waiting.
Looping on quota_exhausted instead of stopping until the window resets.
Rendering a refused field (unavailable is present) as 0. Carry the refusal token through.

Production patterns

Caching, key safety, and SEC loading states around the loop.

Get started

Guides

Agents

MCP

Reference

Resolve coverage before you spend the batch

Concurrency follows the minute limit

A bounded worker pool

Watching for new data

Keep SEC-backed tools out of a tight loop

Where batches go wrong

Production patterns

​Resolve coverage before you spend the batch

​Concurrency follows the minute limit

​A bounded worker pool

​Watching for new data

​Keep SEC-backed tools out of a tight loop

​Where batches go wrong

Production patterns

Resolve coverage before you spend the batch

Concurrency follows the minute limit

A bounded worker pool

Watching for new data

Keep SEC-backed tools out of a tight loop

Where batches go wrong