# noxstock agent context

noxstock is a read-only US-listed stock and ETF context API over REST and hosted MCP. REST routes are authenticated GET /v2/* calls. Hosted MCP is at https://api.noxstock.com/mcp and uses X-API-Key.

Agent rules: preserve envelopes, freshness, as_of, market_status, units, signs, unavailable states, and calls/tools used. Treat freshness: "unsupported" as a fact. Do not invent ETF holdings, ownership/13F, consensus, price targets, transcripts, news, options, execution, or investment advice. Retry only when error.retryable is true.


# Core concepts (/docs/concepts)



noxstock is deliberately small: authenticated `GET /v2/*` routes, one response envelope, explicit freshness, and fields with documented units. A client that respects four contracts can handle every current route without per-endpoint special cases. Each contract has one owner page that states it in full.

<CardGroup cols="2">
  <Card title="Response model" icon="braces" href="/docs/reference/response-model">
    Success is exactly `{ "data": ... }`; failure is exactly `{ "error": { "code", "message", "retryable" } }`. Never parse a raw object at the top level.
  </Card>

  <Card title="Freshness" icon="clock" href="/docs/reference/freshness">
    `freshness`, `as_of`, and `market_status` tell you how current a response is before you show or cache it.
  </Card>

  <Card title="Units and fields" icon="ruler" href="/docs/reference/units-and-fields">
    `_usd` is whole U.S. dollars, `_pct` is a percentage rather than a decimal, and signs are meaningful.
  </Card>

  <Card title="Coverage and gaps" icon="layers" href="/docs/reference/coverage-and-gaps">
    5,119 US-listed symbols, plus which data families do not apply to foreign filers and ETFs.
  </Card>
</CardGroup>

Two design choices follow from those contracts and surprise people often enough to call out here.

## Unsupported is not an error [#unsupported-is-not-an-error]

When a route does not apply to a symbol or asset type, you get HTTP 200 with a normal `data` envelope and `freshness: "unsupported"`, not an error. For example, `/v2/earnings` on an ETF returns 200 with an `unsupported` reason rather than a `4xx`. Branch on `freshness` before you branch on HTTP status.

## Nulls and omissions are intentional [#nulls-and-omissions-are-intentional]

noxstock does not fill unknowns with fake precision. A field that cannot be sourced for a given symbol does not become a guessed number. Instead, structured fields that go missing come back as a small envelope of their own:

```json title="GET /v2/snapshot?symbol=SPY (one field, trimmed)"
{
  "pe_ttm": {
    "available": false,
    "reason": "etf_no_earnings"
  }
}
```

That shape is the live SPY snapshot's `fundamentals_quick.pe_ttm`; an ETF has no earnings, so the multiple carries a machine-readable `reason` instead of a value. The same pattern guards financial-company metrics, where cash-flow and EV ratios mislead: snapshot suppresses a bank's FCF yield with `reason: "fcf_yield_suppressed_for_financials"`, while valuation and fundamentals suppress EV multiples, FCF yield, and interest coverage with `reason: "financial_company_metric_not_meaningful"`. Branch on the envelope shape, not on a specific reason string — reasons are endpoint-specific.

Asset type also decides which routes carry data at all. ETFs answer market-data routes like `/v2/snapshot`, `/v2/technicals`, `/v2/price-action`, and `/v2/history`, and return `unsupported` for stock-only routes like `/v2/earnings`, `/v2/fundamentals`, and `/v2/insider`. ETF profiles return fund facts; holdings are not part of v2.

## REST and MCP share one source of truth [#rest-and-mcp-share-one-source-of-truth]

MCP tools are read-only REST passthroughs. A successful tool call returns the REST `data` envelope unchanged; a failure renders as `[CODE] message (retryable: true|false)`. When the REST/OpenAPI contract and an MCP display disagree, the REST contract wins.


# noxstock docs (/docs)



noxstock is a read-only API for compact US-listed stock and ETF context. The same data is available over REST and over a hosted MCP server, and every response is JSON shaped to be parsed by an app or an agent without endpoint-specific guessing.

Reach for it when you need a fast answer to: what is this symbol, how is it trading, how expensive is it, what do its filings or insiders say, and how fresh is that data.

## Start here [#start-here]

Pick the surface that matches how you call APIs. Both authenticate with the same `nxs_` key in the `X-API-Key` header.

<CardGroup cols="2">
  <Card title="REST quickstart" icon="terminal" href="/docs/quickstart">
    Create a key, call `GET /v2/snapshot?symbol=AAPL`, and read the response. Five minutes from zero to a parsed snapshot.
  </Card>

  <Card title="Hosted MCP" icon="plug" href="/docs/mcp/hosted">
    Point an MCP client at `https://api.noxstock.com/mcp` and call the read-only `noxstock_*` tools that wrap the same routes.
  </Card>
</CardGroup>

## Coverage [#coverage]

5,119 US-listed symbols on NYSE and NASDAQ: 5,062 stocks and 57 ETFs. Every stock resolves to an SEC filer; daily price history runs back up to 5 years. Some data families do not apply to every symbol, so check [coverage and gaps](/docs/reference/coverage-and-gaps) before you commit to a route.

## What to call for what [#what-to-call-for-what]

Start narrow with `/v2/search`, `/v2/coverage`, and `/v2/snapshot`, then add depth only when the question needs it. Routes beyond the four Free ones need Starter or Builder. The [endpoint guide](/docs/guides/choose-endpoints) maps jobs to the smallest route set.

| Need                       | Routes                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| Discovery and events       | `/v2/search`, `/v2/coverage`, `/v2/calendar`                                                      |
| First-pass context         | `/v2/snapshot`, `/v2/profile`                                                                     |
| Valuation and fundamentals | `/v2/valuation`, `/v2/fundamentals`, `/v2/earnings`, `/v2/dividends`                              |
| Price behavior             | `/v2/technicals`, `/v2/price-action`, `/v2/history`, `/v2/compare`                                |
| SEC and insider context    | `/v2/filings`, `/v2/filings/{accession}`, `/v2/filings/{accession}/section/{name}`, `/v2/insider` |

<Note title="Free plan">
  Free keys can call `/v2/search`, `/v2/coverage`, `/v2/snapshot`, and `/v2/valuation`. Starter and Builder reach every route. See [plans and limits](/docs/reference/plans-and-limits) for rate limits and quotas.
</Note>

## What it is not [#what-it-is-not]

noxstock does not trade or execute, and it is not:

* a real-time exchange-grade market data feed
* options, L2/order-book, or global-equities coverage
* analyst consensus, price targets, transcripts, news, or ownership/13F data
* a screener or full cross-symbol database
* investment advice

## Next step [#next-step]

New to the API? Start with the [REST quickstart](/docs/quickstart). If you already know the shape of the data, the [API reference](/docs/api-reference/overview) lists every route, param, and field.


# Quickstart (/docs/quickstart)



Make your first REST call from a server. By the end you have a key in your environment, a working `GET /v2/snapshot?symbol=AAPL`, and code that reads both the success and error envelopes.

<Steps>
  <Step>
    ### Create an API key [#create-an-api-key]

    Open the keys page at `https://noxstock.com/dashboard/keys`, create a key, and copy it before you close the dialog. The raw secret is shown once. Keys start with `nxs_` and travel in the `X-API-Key` header. New keys start on the Free plan — `search`, `coverage`, `snapshot`, and `valuation`; see [plans and limits](/docs/reference/plans-and-limits) for the rest.

    <Warning>
      Keep noxstock keys server-side only. Never put them in frontend code, browser bundles, public repos, logs, screenshots, support chats, or prompts.
    </Warning>
  </Step>

  <Step>
    ### Set your environment [#set-your-environment]

    ```bash
    export NOXSTOCK_API_BASE_URL="https://api.noxstock.com"
    export NOXSTOCK_API_KEY="<your_noxstock_api_key>"
    ```
  </Step>

  <Step>
    ### Make the first call [#make-the-first-call]

    `/v2/snapshot` is the best first call for most apps: it returns quote, performance, 52-week range, quick valuation, sector, and industry in one response.

    ```bash
    curl -sS "$NOXSTOCK_API_BASE_URL/v2/snapshot?symbol=AAPL" \
      -H "X-API-Key: $NOXSTOCK_API_KEY"
    ```
  </Step>

  <Step>
    ### Read the success envelope [#read-the-success-envelope]

    Success is always wrapped in `data`. The response below is trimmed; the live payload also carries a full `performance` block, a `range_52w` block, and roughly a dozen more `fundamentals_quick` fields. The [response model](/docs/reference/response-model) documents the wrapper in full.

    ```json title="GET /v2/snapshot?symbol=AAPL (trimmed)"
    {
      "data": {
        "symbol": "AAPL",
        "name": "Apple Inc",
        "currency": "USD",
        "as_of": "2026-06-05T14:19:06Z",
        "freshness": "intraday",
        "market_status": "open",
        "cache_age_seconds": 0,
        "quote": {
          "price": 314.86,
          "change_abs": 3.63,
          "change_pct": 1.17,
          "previous_close": 311.23,
          "volume": 235657
        },
        "asset_type": "stock",
        "fundamentals_quick": {
          "market_cap_usd": 4569211202200,
          "pe_ttm": 37.28,
          "fcf_yield_pct": 2.83,
          "dividend_yield_pct": 0.34
        },
        "sector": "Technology",
        "industry": "Consumer Electronics"
      }
    }
    ```

    Read these before you show or cache the result:

    * `data.symbol` is the resolved ticker.
    * `data.freshness` is one of `intraday`, `end_of_day`, `stale`, `degraded`, or `unsupported`. See [freshness](/docs/reference/freshness).
    * `data.as_of` is the upstream timestamp when available, otherwise generation time, always UTC ISO-8601.
    * `cache_age_seconds` is how long the served data has been cached; `0` means freshly computed.

    `_usd` fields are whole U.S. dollars and `_pct` fields are percentages, not decimals; [units and fields](/docs/reference/units-and-fields) covers every convention.
  </Step>

  <Step>
    ### Handle the error envelope [#handle-the-error-envelope]

    Failures are always wrapped in `error`. Retry only when `error.retryable` is `true`.

    ```json
    {
      "error": {
        "code": "RATE_LIMITED",
        "message": "Rate limit exceeded. Please slow request rate and retry.",
        "retryable": true
      }
    }
    ```

    The four errors you hit first all map to a distinct HTTP status, and none of them are retryable. Fix the cause before you call again:

    | Code                    | HTTP | Fix                                   |
    | ----------------------- | ---- | ------------------------------------- |
    | `UNAUTHORIZED`          | 401  | Set a valid key in `X-API-Key`.       |
    | `PLAN_UPGRADE_REQUIRED` | 403  | The route needs Starter or Builder.   |
    | `SYMBOL_INVALID`        | 400  | Symbol must match the ticker grammar. |
    | `SYMBOL_UNKNOWN`        | 404  | Resolve the ticker with `/v2/search`. |

    Successful responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; a `429` carries them too, plus `Retry-After` in seconds. Other error responses do not include them, so read your budget from successes. The full table and retry policy live on the [error codes](/docs/reference/error-codes) page.
  </Step>
</Steps>

## Optional fit checks [#optional-fit-checks]

Run these before you store a user-entered symbol or kick off batch work.

```bash
# Resolve a company name to symbols.
curl -sS "$NOXSTOCK_API_BASE_URL/v2/search?query=apple" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"

# Confirm the symbol is supported and see its asset type.
curl -sS "$NOXSTOCK_API_BASE_URL/v2/coverage?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

## Call it from code [#call-it-from-code]

Both clients check the envelope before the HTTP status, because a `4xx`/`5xx` still carries a structured `error`. Keep the key server-side; never ship it to the browser.

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="snapshot.py"
    import os

    import httpx

    base_url = os.environ.get("NOXSTOCK_API_BASE_URL", "https://api.noxstock.com")
    api_key = os.environ["NOXSTOCK_API_KEY"]

    with httpx.Client(
        base_url=base_url,
        headers={"X-API-Key": api_key},
        timeout=10.0,
    ) as client:
        response = client.get("/v2/snapshot", params={"symbol": "AAPL"})
        body = response.json()

        if "error" in body:
            error = body["error"]
            raise RuntimeError(
                f"{error['code']}: {error['message']} (retryable={error['retryable']})"
            )

        response.raise_for_status()
        data = body["data"]
        print(data["symbol"], data["freshness"], data["as_of"], data["quote"]["price"])
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="snapshot.ts"
    type NoxstockEnvelope<T> =
      | { data: T }
      | { error: { code: string; message: string; retryable: boolean } };

    type Snapshot = {
      symbol: string;
      freshness: string;
      as_of: string;
      quote?: { price?: number };
    };

    const baseUrl = process.env.NOXSTOCK_API_BASE_URL ?? "https://api.noxstock.com";
    const apiKey = process.env.NOXSTOCK_API_KEY;

    if (!apiKey) {
      throw new Error("Missing NOXSTOCK_API_KEY");
    }

    async function noxstockGet<T>(path: string, params: Record<string, string>) {
      const url = new URL(path, baseUrl);
      url.search = new URLSearchParams(params).toString();

      const response = await fetch(url, {
        headers: { "X-API-Key": apiKey },
        signal: AbortSignal.timeout(10_000),
        cache: "no-store",
      });

      const body = (await response.json()) as NoxstockEnvelope<T>;

      if ("error" in body) {
        const error = new Error(`${body.error.code}: ${body.error.message}`) as Error & {
          retryable?: boolean;
        };
        error.retryable = body.error.retryable;
        throw error;
      }

      if (!response.ok) {
        throw new Error(`HTTP ${response.status} without a noxstock error envelope`);
      }

      return body.data;
    }

    async function main() {
      const snapshot = await noxstockGet<Snapshot>("/v2/snapshot", { symbol: "AAPL" });
      console.log(snapshot.symbol, snapshot.freshness, snapshot.as_of, snapshot.quote?.price);
    }

    main();
    ```
  </Tab>
</Tabs>

## Next steps [#next-steps]

Most apps call `GET /v2/valuation?symbol=AAPL` next; it pairs with snapshot and is available on Free keys. If your question is not valuation, the [endpoint guide](/docs/guides/choose-endpoints) maps jobs to routes.

<CardGroup cols="3">
  <Card title="Choose endpoints" icon="route" href="/docs/guides/choose-endpoints">
    Pick the smallest route set for your job.
  </Card>

  <Card title="Errors and retries" icon="rotate-cw" href="/docs/guides/errors-and-retries">
    Build retry behavior around `error.retryable`.
  </Card>

  <Card title="Hosted MCP" icon="plug" href="/docs/mcp/hosted">
    Connect MCP if you are building agents.
  </Card>
</CardGroup>


# Agent instructions (/docs/agents/instructions)



Paste this block into the system or developer prompt of any agent that can reach noxstock over REST or MCP. It is the one place the operating rules live; recipes and the skill file point back here. Set `NOXSTOCK_API_KEY` in the agent's environment first ([create a key](https://noxstock.com/dashboard/keys)).

```text title="noxstock-system-prompt.txt"
You use noxstock for US-listed stock and ETF context. It covers NYSE and NASDAQ
listings only: no options, futures, crypto, FX, or non-US equities.

Connection
- Hosted MCP: connect to https://api.noxstock.com/mcp and send the header
  X-API-Key: $NOXSTOCK_API_KEY. Confirm the noxstock_* tools loaded, then
  smoke-test noxstock_snapshot with symbol "AAPL". MCP is read-only and calls REST.
- REST: base URL https://api.noxstock.com, same X-API-Key header on every request.
  When MCP and REST disagree, REST/OpenAPI is the source of truth.

Envelope
- Success is {"data": ...}. Failure is {"error": {"code", "message", "retryable"}}.
- A 200 with freshness "unsupported" plus a machine-readable reason is a real
  answer, not an error. Report it as "not available from noxstock", do not retry it.

Default call sequence
- If the user names a company or fund, call search first to resolve the symbol.
- Call coverage before you store, batch, or deeply analyze a symbol.
- Call snapshot for most single-symbol questions, then add only what the question
  needs: valuation, fundamentals, compare (2-4 tickers), filings list -> filing ->
  filing section for SEC text, insider for Form 4 activity, technicals + price-action
  for trend and timing, history only when you need a time series.

Plan access
- A Free key calls search, coverage, snapshot, and valuation only. Anything else
  returns PLAN_UPGRADE_REQUIRED (403, not retryable).
- Starter and Builder keys reach every route and tool.

Output rules
- Answer first. Then show the few facts that support it, then freshness, then the
  calls you made.
- Preserve every value as returned: units, signs, percentages, fiscal periods,
  accessions, filing dates, as_of timestamps, freshness, market_status, and any
  notices or null/unavailable reasons. Never round away a sign or invent precision.
- Never invent data noxstock does not return. That includes ETF holdings, ownership
  or 13F positions, analyst consensus or price targets, earnings-call transcripts,
  options, news, and non-US equities. If a field is missing, say
  "not available from noxstock" and stop.
- Summarize SEC risk, MD&A, business, or press-release content only from the filing
  section text noxstock returns. Do not blend in news, consensus, the web, or memory.
- Report data; do not advise. No buy/sell/hold verdict, price target, or trade.

Retry rule
- Retry only when error.retryable is true, and honor Retry-After when present.
  Do not retry UNAUTHORIZED, PLAN_UPGRADE_REQUIRED, SYMBOL_UNKNOWN, SYMBOL_INVALID,
  PARAM_INVALID, or an unsupported data state without changing the request.
```

Two facts above are owned elsewhere and worth following: the full [error codes and retry policy](/docs/reference/error-codes), and which [plan reaches which route](/docs/reference/plans-and-limits).

<Card title="Agent recipes" icon="bot" href="/docs/agents/recipes">
  See these rules applied: prompt, exact calls, and a filled answer from real fixtures.
</Card>


# Agent recipes (/docs/agents/recipes)



Each recipe maps a class of user prompt to the smallest set of noxstock calls and an answer template. The output rules these templates assume (answer first, preserve freshness and signs, no advice) live once in the [agent instructions](/docs/agents/instructions) — paste that block into your agent and the templates below fall out of it.

REST paths and MCP tools are listed side by side. MCP arguments use native JSON types: lists are arrays (`["10-K","10-Q"]`), not comma-separated strings. Plan access matters here: a Free key covers the snapshot/valuation recipes in full; `insider`, `compare`, `filings`, `technicals`, and `price-action` need Starter or Builder ([plans and limits](/docs/reference/plans-and-limits)).

## One-symbol brief [#one-symbol-brief]

Serves prompts like "What's going on with AAPL?", "Give me a read on Apple", "Should I be paying attention to NVDA?" — a single ticker, no specific sub-topic.

Calls: snapshot is usually enough. Add insider (Starter+) only when the prompt hints at ownership or recent activity; add valuation when it hints at price-versus-worth. On a Free key, skip the activity line and say insider data was not consulted rather than guessing.

<Tabs items="[&#x22;REST&#x22;, &#x22;MCP&#x22;]">
  <Tab value="REST">
    ```text
    GET /v2/snapshot?symbol=AAPL
    GET /v2/insider?symbol=AAPL          # only if activity is in scope
    ```
  </Tab>

  <Tab value="MCP">
    ```text
    noxstock_snapshot({ "symbol": "AAPL" })
    noxstock_insider({ "symbol": "AAPL" })   # only if activity is in scope
    ```
  </Tab>
</Tabs>

Template:

```text
Answer: <one factual sentence — what the symbol is doing right now>

Setup
- <price, day change, recent performance, 52-week position from snapshot>
- <sector/industry or asset_type if it matters>

Activity / caveats
- <insider net direction, or any unsupported/stale/null reasons>

Freshness
- Snapshot: <freshness>, as_of <timestamp>, market_status <status>
- Insider: <freshness>, as_of <timestamp>

Calls used
- <routes or tool names>
```

Filled with the live AAPL `snapshot` and `insider` fixtures (numbers copied verbatim; the insider rollup returns ten recent transactions and a 90-day summary, trimmed here to the relevant lines):

```text title="aapl-brief.txt"
Answer: AAPL is trading at 314.86, up 1.17% on the day and up 54.06% over the past
year (+25.56% vs SPY), sitting near the top of its 52-week range.

Setup
- Price 314.86, day change +1.17%. 52-week range 194.30-316.94; position 95.3% of
  range, 1.8% below the 52-week high.
- 1-year +54.06%, vs SPY +25.56%. Sector: Technology, Consumer Electronics.
- Trailing P/E 37.28, FCF yield 2.83%, dividend yield 0.34%.

Activity / caveats
- Insider 90-day Form 4 rollup: net direction "selling". 0 open-market buys vs 13
  open-market sells, net_shares_market_only -397,759, net_value_usd -$111,705,105.08.
  Largest sale: Arthur D Levinson (Director), 50,000 shares at 311.02 on 2026-05-27,
  not under a 10b5-1 plan.
- Notice: recent_transactions_limited_to_10. The full rollup scans the latest 200
  Form 4 filings; only the 10 most recent transactions are itemized.

Freshness
- Snapshot: intraday, as_of 2026-06-05T14:19:06Z, market_status open.
- Insider: end_of_day, as_of 2026-06-05T06:45:45Z.

Calls used
- snapshot, insider
```

Note the two `as_of` timestamps differ: the quote is intraday, the Form 4 rollup is end-of-day. Surface both rather than collapsing them into one.

## Valuation check [#valuation-check]

Serves "Is AAPL expensive?", "Is NVDA cheap right now?", "How does the multiple look?". Snapshot gives price context; valuation gives the multiples and their 5-year position. Skip fundamentals unless the user asks *why* the multiple is what it is.

<Tabs items="[&#x22;REST&#x22;, &#x22;MCP&#x22;]">
  <Tab value="REST">
    ```text
    GET /v2/snapshot?symbol=NVDA
    GET /v2/valuation?symbol=NVDA
    ```
  </Tab>

  <Tab value="MCP">
    ```text
    noxstock_snapshot({ "symbol": "NVDA" })
    noxstock_valuation({ "symbol": "NVDA" })
    ```
  </Tab>
</Tabs>

Template:

```text
Answer: <cheap / expensive / mixed / not enough valuation context — from returned fields only>

Why
- valuation_context: anchor <metric>, value <x>, percentile_5y <n>, position <label>
- <supporting multiples and yields, keeping _pct and _usd>

Caveats
- <ETFs return freshness "unsupported" for valuation; financial-company guardrails; stale/degraded data>

Freshness
- Valuation: <freshness>, as_of <timestamp>, market_status <status>

Calls used
- snapshot, valuation
```

ETFs do not get valuation multiples — `/v2/valuation` for an ETF returns HTTP 200 with `freshness: "unsupported"`. Treat that as the answer, not a failure.

## Compare a basket [#compare-a-basket]

Serves "Compare NVDA, AMD, and INTC", "How do these three stack up?". One `compare` call returns an aligned row per symbol. If the user wants more, deepen only the symbol they fixate on.

`symbols` takes 2-4 tickers; 5 or more returns `PARAM_INVALID`. The default field set is `price,pct_1y,vs_spy_pct_1y,pe_ttm,rsi_14,trending`; any field a symbol cannot supply is listed in `fields_omitted_by_symbol`.

<Tabs items="[&#x22;REST&#x22;, &#x22;MCP&#x22;]">
  <Tab value="REST">
    ```text
    GET /v2/compare?symbols=NVDA,AMD,INTC
    ```
  </Tab>

  <Tab value="MCP">
    ```text
    noxstock_compare({ "symbols": ["NVDA", "AMD", "INTC"] })
    ```
  </Tab>
</Tabs>

Template:

```text
Answer: <one-sentence comparison — a contrast, not a recommendation>

Scorecard
| Symbol | <field> | <field> | <field> |
| --- | ---: | ---: | ---: |
| <symbol> | <value> | <value> | <value> |

Notes
- fields_requested: <list>
- fields_omitted_by_symbol: <only if non-empty>

Freshness
- Compare: <freshness>, as_of <timestamp>, market_status <status>

Calls used
- compare
```

A negative `pe_ttm` means trailing losses, not a cheap multiple — keep the sign and say so.

## SEC risk review [#sec-risk-review]

Serves "What are the risks in Apple's latest 10-K?", "Summarize Tesla's risk factors". Resolve the symbol, list filings, pick the latest 10-K's accession, then pull the section text and summarize *only* that text.

<Tabs items="[&#x22;REST&#x22;, &#x22;MCP&#x22;]">
  <Tab value="REST">
    ```text
    GET /v2/filings?symbol=AAPL&form=10-K&limit=3
    GET /v2/filings/0000320193-25-000079
    GET /v2/filings/0000320193-25-000079/section/risk_factors
    ```
  </Tab>

  <Tab value="MCP">
    ```text
    noxstock_filings_list({ "symbol": "AAPL", "forms": ["10-K"], "limit": 3 })
    noxstock_filings_get({ "accession": "0000320193-25-000079" })
    noxstock_filings_section({ "accession": "0000320193-25-000079", "name": "risk_factors" })
    ```
  </Tab>
</Tabs>

Template:

```text
Answer: <1-2 sentence summary drawn from the section text only>

Key risks from the section
- <point from text>
- <point from text>
- <point from text>

Source
- Form <form>, accession <accession>, filed <filing_date>, period <period_of_report>
- Section: <section>, char_count <n>

Freshness
- Filing/section: <freshness>, as_of <timestamp>

Calls used
- filings_list, filings_get, filings_section
```

The risk\_factors section for that AAPL accession returns `char_count` 68069 — far more than fits one answer. Summarize the themes (macro and tariff exposure, supply-chain concentration, competition, legal and regulatory) and say the text was condensed. Do not add a single fact that is not in the returned text: no news, no consensus, no stock move, no memory.

The 926 foreign private issuers (\~18% of the universe) file 20-F/40-F/6-K, so `/v2/filings` returns `unsupported` for them — see [coverage and gaps](/docs/reference/coverage-and-gaps).

## Insider scan [#insider-scan]

Serves "Any notable insider activity in AAPL?", "Are executives selling?". One `insider` call returns the trailing 90-day Form 4 rollup plus recent transactions.

`limit` ranges 1-200 (default 10). The rollup scans the latest 200 Form 4 filings; if it truncates, `summary_90d.notices` says so.

<Tabs items="[&#x22;REST&#x22;, &#x22;MCP&#x22;]">
  <Tab value="REST">
    ```text
    GET /v2/insider?symbol=AAPL&limit=20
    ```
  </Tab>

  <Tab value="MCP">
    ```text
    noxstock_insider({ "symbol": "AAPL", "limit": 20 })
    ```
  </Tab>
</Tabs>

Template:

```text
Answer: <notable / quiet / not available — from summary_90d.net_direction>

90-day Form 4 summary
- Open-market: <buy_count> buys, <sell_count> sells, net_shares_market_only <signed>, net_value_usd <signed>
- All activity: <transactions> total, net_shares_all_kinds <signed>, by kind <transactions_by_kind>
- Notices: <summary_90d.notices if present>

Recent transactions
- <transaction_date>: <insider_name> (<role>), <transaction_kind>, <shares>, <value_usd or unavailable reason>, 10b5-1 <true/false>

Freshness
- Insider: <freshness>, as_of <timestamp>

Calls used
- insider
```

Some transactions have no price: gifts and exercises return `value_usd` as `{ "available": false, "reason": ... }`. Keep the reason; do not impute a dollar value. Selling pressure in the rollup is not a sell signal — report it, do not advise on it.

## Technical timing [#technical-timing]

Serves "Is AAPL overbought?", "Is the trend extended?". Technicals gives indicators and zones; price-action gives volume, extremes, gaps, and drawdowns. Add history only when the user wants the actual series.

<Tabs items="[&#x22;REST&#x22;, &#x22;MCP&#x22;]">
  <Tab value="REST">
    ```text
    GET /v2/technicals?symbol=AAPL
    GET /v2/price-action?symbol=AAPL
    GET /v2/history?symbol=AAPL&series=close,rsi_14&range=1y&cadence=daily   # only for a chart
    ```
  </Tab>

  <Tab value="MCP">
    ```text
    noxstock_technicals({ "symbol": "AAPL" })
    noxstock_price_action({ "symbol": "AAPL" })
    noxstock_history({ "symbol": "AAPL", "series": ["close", "rsi_14"], "period": "1y", "cadence": "daily" })
    ```
  </Tab>
</Tabs>

Template:

```text
Answer: <extended / neutral / weak / not enough technical context>

Setup
- RSI and zone (note daily vs weekly), distance from moving averages, ADX/trend
- 52-week distance, recent drawdown, volume vs average, streak/gap context

Caveats
- market_status is session state, not execution readiness
- <degraded/null long-window fields if present>

Freshness
- Technicals: <freshness>, as_of <timestamp>, market_status <status>
- Price action: <freshness>, as_of <timestamp>, market_status <status>

Calls used
- technicals, price_action
```

The history tool argument is named `period` — it maps to REST's `range` (whose own legacy alias is also `period`). Do not imply execution readiness or tell the user to enter or exit a trade.

<Card title="Choose endpoints" icon="route" href="/docs/guides/choose-endpoints">
  For a prompt no recipe covers, pick the smallest route set by job.
</Card>


# Agent skill (/docs/agents/skill)



The canonical skill lives at [https://noxstock.com/SKILL.md](https://noxstock.com/SKILL.md). The block on this page mirrors that file; the URL is canonical, so point your agent at it rather than copying a snapshot that can drift. The file uses progressive disclosure — a tight body plus links — so it loads cheaply and an agent only fetches the deeper pages when a task needs them.

## Install it [#install-it]

A `SKILL.md` with frontmatter `name` and `description` is the portable format across today's coding agents. Drop it into the agent's skills directory and it gets picked up. The honest generic: &#x2A;*add `SKILL.md` to your agent's skills directory.** Exact paths by agent:

<Tabs items="[&#x22;Claude Code&#x22;, &#x22;Codex CLI&#x22;, &#x22;Gemini CLI&#x22;, &#x22;Cursor&#x22;]">
  <Tab value="Claude Code">
    ```bash
    mkdir -p .claude/skills/noxstock
    curl -sS https://noxstock.com/SKILL.md -o .claude/skills/noxstock/SKILL.md
    ```

    Project-scoped under `.claude/skills/`; use `~/.claude/skills/` for every project.
  </Tab>

  <Tab value="Codex CLI">
    ```bash
    mkdir -p .codex/skills/noxstock
    curl -sS https://noxstock.com/SKILL.md -o .codex/skills/noxstock/SKILL.md
    ```

    Drop it in the agent's skills directory; Codex reads the `name` and `description` frontmatter to decide when it applies.
  </Tab>

  <Tab value="Gemini CLI">
    ```bash
    mkdir -p .gemini/skills/noxstock
    curl -sS https://noxstock.com/SKILL.md -o .gemini/skills/noxstock/SKILL.md
    ```

    Place it in the agent's skills directory. If your setup keys off context files instead, reference the URL from there.
  </Tab>

  <Tab value="Cursor">
    ```bash
    mkdir -p .cursor/skills/noxstock
    curl -sS https://noxstock.com/SKILL.md -o .cursor/skills/noxstock/SKILL.md
    ```

    Add it to the skills directory, or paste the body into a Cursor rule so it loads with the project.
  </Tab>
</Tabs>

<Note>
  Directory names vary across agents and versions; the constant is "a `SKILL.md` with `name` + `description` in the skills directory." If yours expects a different location, move the file there — the content is identical.
</Note>

## The file [#the-file]

This is the current `SKILL.md`, verbatim:

````md
---
name: noxstock
description: >-
  Structured context for US-listed stocks and ETFs (NYSE/NASDAQ): symbol search,
  snapshot, valuation, fundamentals, earnings, dividends, technicals, price action,
  history, compare, SEC filings, and insider Form 4 activity. Use over hosted MCP or
  REST when a task needs quote, performance, valuation, financial, technical, SEC, or
  insider data for a US ticker. Not for trading, options, real-time L2, or non-US equities.
---

# noxstock

## Use it for

US-listed stock and ETF context: resolve a company or fund name to a symbol, then
pull snapshot, valuation, fundamentals, earnings, dividends, technicals, price action,
price history, a 2-4 symbol compare, SEC filings (list, metadata, section text), or the
trailing 90-day insider Form 4 rollup. Coverage is NYSE and NASDAQ listings.

## Don't use it for

Trading or order execution, exchange-grade real-time or L2/order-book data, options,
futures, crypto, FX, non-US equities, analyst consensus or price targets, earnings-call
transcripts, news, ownership/13F positions, or investment advice. If asked for any of
these, say "not available from noxstock."

## Setup

Prefer hosted MCP. Set `NOXSTOCK_API_KEY` first (create a key at
https://noxstock.com/dashboard/keys), then add the server:

```json
{
  "mcpServers": {
    "noxstock": {
      "url": "https://api.noxstock.com/mcp",
      "headers": { "X-API-Key": "$NOXSTOCK_API_KEY" }
    }
  }
}
```

Smoke-test: confirm the `noxstock_*` tools loaded, then call
`noxstock_snapshot({ "symbol": "AAPL" })`. A success returns `{ "data": ... }` with
`freshness` and `as_of`. MCP tool arguments use native JSON types — lists are arrays
(`["10-K","10-Q"]`), not comma-separated strings.

REST fallback (same key, every request carries the header):

```bash
curl -sS "https://api.noxstock.com/v2/snapshot?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

MCP is read-only and calls REST under the hood. When the two disagree, REST/OpenAPI is
the source of truth.

## Plans

A Free key calls search, coverage, snapshot, and valuation only; every other route
returns `PLAN_UPGRADE_REQUIRED`. Starter and Builder keys reach all routes and tools.
See https://noxstock.com/docs/reference/plans-and-limits.

## Default call sequence

1. If the user names a company or fund, call search to resolve the symbol.
2. Call coverage before storing, batching, or deeply analyzing a symbol.
3. Call snapshot for most single-symbol questions.
4. Add only what the question needs: valuation, fundamentals, compare (2-4 tickers),
   filings list -> filing -> filing section for SEC text, insider for Form 4 activity,
   technicals + price-action for trend and timing, history only for a time series.

## Output rules

- Answer first, then the few supporting facts, then freshness, then the calls you made.
- Parse the envelope: success is top-level `data`; failure is top-level `error` with
  `code`, `message`, and `retryable`. Retry only when `retryable` is true and honor
  `Retry-After`.
- Preserve every value as returned — units, signs, `_pct`, `_usd`, fiscal periods,
  accessions, filing dates, `as_of`, `freshness`, `market_status`, notices, and
  null/unavailable reasons. Never round away a sign or invent precision.
- Treat `freshness: "unsupported"` and `available: false` reasons as facts. Say "not
  available from noxstock" instead of guessing; do not retry these states.
- Summarize SEC risk/MD&A/business/press-release content only from the returned filing
  section text. Do not blend in news, consensus, the web, or memory.
- Report data; do not advise. No buy/sell/hold verdict, price target, or trade
  instruction. Keep the API key server-side — never in client code, logs, or prompts.

## Go deeper

- Agent recipes (prompt -> calls -> answer): https://noxstock.com/docs/agents/recipes
- Choose the right endpoint: https://noxstock.com/docs/guides/choose-endpoints
- Error codes and retry policy: https://noxstock.com/docs/reference/error-codes
- Hosted MCP setup: https://noxstock.com/docs/mcp/hosted
- API reference: https://noxstock.com/docs/api-reference/overview
````

## Route and tool access [#route-and-tool-access]

The skill points agents at the right call; this table is the access map behind it. Each route's MCP tool carries the same name with a `noxstock_` prefix.

| Need                | REST route                                           | Plan             |
| ------------------- | ---------------------------------------------------- | ---------------- |
| Company/name lookup | `GET /v2/search?query=apple`                         | Free             |
| Coverage check      | `GET /v2/coverage?symbol=AAPL`                       | Free             |
| First-pass context  | `GET /v2/snapshot?symbol=AAPL`                       | Free             |
| Valuation           | `GET /v2/valuation?symbol=AAPL`                      | Free             |
| Profile             | `GET /v2/profile?symbol=AAPL`                        | Starter, Builder |
| Statements          | `GET /v2/fundamentals?symbol=AAPL&period=quarter`    | Starter, Builder |
| Earnings            | `GET /v2/earnings?symbol=AAPL`                       | Starter, Builder |
| Dividends           | `GET /v2/dividends?symbol=AAPL`                      | Starter, Builder |
| Technicals          | `GET /v2/technicals?symbol=AAPL`                     | Starter, Builder |
| Price action        | `GET /v2/price-action?symbol=AAPL`                   | Starter, Builder |
| History             | `GET /v2/history?symbol=AAPL&series=close&range=1y`  | Starter, Builder |
| Compare 2-4 symbols | `GET /v2/compare?symbols=AAPL,MSFT`                  | Starter, Builder |
| Calendar            | `GET /v2/calendar?symbol=AAPL`                       | Starter, Builder |
| Filing list         | `GET /v2/filings?symbol=AAPL&form=10-K,10-Q&limit=5` | Starter, Builder |
| Filing metadata     | `GET /v2/filings/{accession}`                        | Starter, Builder |
| Filing section text | `GET /v2/filings/{accession}/section/{name}`         | Starter, Builder |
| Insider activity    | `GET /v2/insider?symbol=AAPL`                        | Starter, Builder |

<Card title="Agent recipes" icon="bot" href="/docs/agents/recipes">
  Once the skill is installed, these show the call sequences it should produce.
</Card>


# API reference overview (/docs/api-reference/overview)



Every product route is a `GET` under `/v2` at `https://api.noxstock.com`, authenticated with your `nxs_` key in the `X-API-Key` header.

```bash
curl "https://api.noxstock.com/v2/snapshot?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

## Routes [#routes]

The access column lists the plans that can call each route. See [plans and limits](/docs/reference/plans-and-limits) for the rate limits and quotas behind those names.

| Route                                        | Access                 | Use                                        |
| -------------------------------------------- | ---------------------- | ------------------------------------------ |
| `GET /v2/search`                             | Free, Starter, Builder | Symbol discovery from a name or query.     |
| `GET /v2/coverage`                           | Free, Starter, Builder | Supported-universe and asset-type check.   |
| `GET /v2/snapshot`                           | Free, Starter, Builder | One-shot market and fundamental context.   |
| `GET /v2/valuation`                          | Free, Starter, Builder | Valuation and multiples context.           |
| `GET /v2/profile`                            | Starter, Builder       | Company and ETF fund facts.                |
| `GET /v2/fundamentals`                       | Starter, Builder       | Income, balance sheet, and cash flow rows. |
| `GET /v2/earnings`                           | Starter, Builder       | Earnings history and context.              |
| `GET /v2/dividends`                          | Starter, Builder       | Dividend and payout history.               |
| `GET /v2/technicals`                         | Starter, Builder       | Technical indicators.                      |
| `GET /v2/price-action`                       | Starter, Builder       | Recent price action and range context.     |
| `GET /v2/history`                            | Starter, Builder       | Selected historical series.                |
| `GET /v2/compare`                            | Starter, Builder       | 2–4 symbol scorecard.                      |
| `GET /v2/calendar`                           | Starter, Builder       | Per-symbol upcoming events.                |
| `GET /v2/filings`                            | Starter, Builder       | Recent SEC filings.                        |
| `GET /v2/filings/{accession}`                | Starter, Builder       | Filing metadata and section index.         |
| `GET /v2/filings/{accession}/section/{name}` | Starter, Builder       | Full section text.                         |
| `GET /v2/insider`                            | Starter, Builder       | Trailing 90-day Form 4 activity.           |

## Query conventions [#query-conventions]

* Symbols are US tickers up to 8 characters; dot share classes such as `BRK.B` normalize to `BRK-B`.
* Multi-value params are comma-separated: `symbols=AAPL,MSFT`, `form=10-K,10-Q`.
* Timestamps are UTC ISO-8601 unless a field documents otherwise.
* Currency fields suffix `_usd`; percent fields suffix `_pct` and are percentages, not decimals.

## Response examples [#response-examples]

The JSON in every endpoint page is a real production payload captured against the live API, trimmed where noted. The [error codes](/docs/reference/error-codes) page lists each code, its HTTP status, and whether it is retryable.

## Playground [#playground]

Generated endpoint pages include a live playground for manual `GET /v2/*` calls. Paste your key into the masked `X-API-Key` field; keys you enter are sent directly to the API for that request and are never stored. Avoid the playground on shared machines.

## OpenAPI [#openapi]

These endpoint pages are generated from the FastAPI OpenAPI spec in `openapi.json`.

<Info>
  If a generated schema and a prose guide disagree, trust the OpenAPI schema and the live API, and file a docs bug so the prose can be corrected.
</Info>


# Batch workflows (/docs/guides/batch-workflows)



There is no bulk endpoint today — one symbol per request. So a batch is your own loop: check coverage first to skip the symbols that cannot answer, fetch a compact snapshot for the rest, and deepen only the shortlist. The rate that loop runs at is set by your plan's per-minute limit, and the code below reads the rate-limit headers to stay under it.

## Check coverage before you spend the batch [#check-coverage-before-you-spend-the-batch]

926 of the 5,119 covered symbols are foreign private issuers that file 20-F/40-F/6-K, so `/v2/filings` and `/v2/insider` return `unsupported` for them; ETFs return `unsupported` for earnings and other stock-only families. Resolve those gaps with one cheap `/v2/coverage` call per symbol before you fan out the expensive routes — see [coverage and gaps](/docs/reference/coverage-and-gaps) for the full universe. Dropping a symbol you know cannot answer is the cheapest request you never make.

For a 2–4 symbol comparison, do not hand-roll a batch at all. `/v2/compare?symbols=AAPL,MSFT,NVDA` does it in one call and returns `fields_omitted_by_symbol` for anything a symbol cannot supply.

## Concurrency follows the minute limit [#concurrency-follows-the-minute-limit]

Pick your in-flight count from the plan's per-minute limit, then leave headroom — bursts and retries eat into it. The [plans and limits](/docs/reference/plans-and-limits) page owns the exact numbers; the mapping for batches:

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

On **Free**, also mind the daily quota: 100 requests a day disappears in one watchlist refresh of 30–40 symbols once you add a coverage call and a snapshot call each. Free batch work needs caching or a small list, and there is no header that counts the daily budget down — the `X-RateLimit-*` headers track the minute bucket, so they look healthy right up until the quota 429 lands. Count your own daily requests. A quota 429 is recognizable by its size: `Retry-After` jumps from seconds to hours (the time until the window resets). The quota math lives on [plans and limits](/docs/reference/plans-and-limits).

A bounded worker pool keeps you at that in-flight count. Both versions below read `X-RateLimit-Remaining` to slow down early and honor `Retry-After` on a 429 instead of hammering through it.

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="batch.py"
    import asyncio
    import httpx

    async def fetch(client, sem, symbol, key):
        async with sem:  # cap in-flight at the semaphore's size
            res = await client.get(
                "https://api.noxstock.com/v2/snapshot",
                params={"symbol": symbol},
                headers={"X-API-Key": key},
            )
            if res.status_code == 429:
                retry_after = float(res.headers.get("Retry-After", 5))
                if retry_after > 120:
                    # Quota 429: Retry-After is the time to the window reset
                    # (hours, not seconds). Stop the batch instead of sleeping.
                    raise RuntimeError(f"quota exhausted; window resets in {retry_after:.0f}s")
                await asyncio.sleep(retry_after)
                return await fetch(client, sem, symbol, key)
            if int(res.headers.get("X-RateLimit-Remaining", 1)) < 5:
                await asyncio.sleep(1)  # near the ceiling, ease off
            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(*(fetch(client, sem, s, key) for s in symbols))
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="batch.ts"
    const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

    async function fetchOne(symbol: string, key: string): Promise<[string, unknown]> {
      const res = await fetch(`https://api.noxstock.com/v2/snapshot?symbol=${symbol}`, {
        headers: { "X-API-Key": key },
      });
      if (res.status === 429) {
        const retryAfter = Number(res.headers.get("Retry-After") ?? 5);
        if (retryAfter > 120) {
          // Quota 429: Retry-After is the time to the window reset (hours).
          throw new Error(`quota exhausted; window resets in ${retryAfter}s`);
        }
        await sleep(retryAfter * 1000);
        return fetchOne(symbol, key);
      }
      if (Number(res.headers.get("X-RateLimit-Remaining") ?? 1) < 5) {
        await sleep(1000); // near the ceiling, ease off
      }
      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 fetchOne(symbol, key));
      });
      await Promise.all(workers);
      return results;
    }
    ```
  </Tab>
</Tabs>

For the full retry semantics — attempt caps, total-wait budget, retrying only `retryable: true` — wrap each request with the loop in [errors and retries](/docs/guides/errors-and-retries). The minimal `Retry-After` handling above keeps a batch from drowning, but it is not the complete policy.

## SEC routes do not belong in a tight loop [#sec-routes-do-not-belong-in-a-tight-loop]

Filing and insider routes read from EDGAR and can be slow cold, so they are the wrong thing to fan out across a list. Run them in a background job, cache filing metadata and section text hard (it does not change), and only pull them for the shortlist a user actually opened. The same applies to `/v2/insider`, which scans the latest 200 Form 4 filings per symbol.

## Where batches go wrong [#where-batches-go-wrong]

* Calling `fundamentals`, `filings`, and `insider` for every watchlist row instead of snapshot-first, then shortlisting.
* Treating `PLAN_UPGRADE_REQUIRED` as retryable and looping on it mid-batch.
* Continuing to send after a 429 instead of waiting `Retry-After`.
* Retrying `unsupported` ETF or foreign-issuer states — they are stable `200`s, not failures.
* Making every missing field look like a zero. Carry the `reason` through.

<CardGroup cols="2">
  <Card title="Production patterns" icon="activity" href="/docs/guides/production-patterns">
    Caching, key safety, and SEC loading states around the loop.
  </Card>

  <Card title="Compare basket" icon="columns-3" href="/docs/guides/compare-basket">
    The one-call scorecard for 2–4 symbols.
  </Card>
</CardGroup>


# Build an equity agent (/docs/guides/build-an-agent)



An agent that answers "Is AAPL extended here?" needs two facts: where the price sits in its recent range, and what the momentum indicators say. That is two calls, not ten. This page traces that question end to end, then shows the two runtimes that carry it: hosted MCP and a REST-backed tool function.

## The tool-selection policy [#the-tool-selection-policy]

Start narrow. The first call is almost always `/v2/snapshot` — it carries price, 52-week position, performance, and quick fundamentals in one payload. Add exactly one call per dimension the question opens, and stop when the question is answered.

"Is AAPL extended here?" has two dimensions: position in range (snapshot covers it) and momentum (snapshot does not). So the agent calls `snapshot`, reads that AAPL is near its 52-week high, then adds `technicals` for RSI, MACD, and trend strength. It does not call `valuation`, `fundamentals`, or `history` — none of them answer "extended."

For routing other question shapes to the right starting endpoint, see [choose endpoints](/docs/guides/choose-endpoints).

## A worked trace [#a-worked-trace]

**User:** Is AAPL extended here?

**Call 1 — snapshot.** The agent asks for position in range first.

```json title="GET /v2/snapshot?symbol=AAPL (trimmed)"
{
  "data": {
    "symbol": "AAPL",
    "as_of": "2026-06-05T14:19:06Z",
    "freshness": "intraday",
    "market_status": "open",
    "quote": { "price": 314.86, "change_pct": 1.17, "previous_close": 311.23 },
    "performance": { "pct_1m": 9.62, "pct_ytd": 15.06, "pct_1y": 54.06, "vs_spy_pct_1y": 25.56 },
    "range_52w": { "high": 316.94, "low": 194.3, "position_pct": 95.3, "drawdown_from_high_pct": -1.8 },
    "asset_type": "stock"
  }
}
```

The full payload also returns `fundamentals_quick`, `sector`, and more — trimmed here to the fields that answer the question. AAPL sits at 95.3% of its 52-week range, 1.8% off the high, up 54% on the year. That reads extended on price. The agent needs momentum to confirm, so it makes one more call.

**Call 2 — technicals.** Same symbol, one new dimension.

```json title="GET /v2/technicals?symbol=AAPL (trimmed)"
{
  "data": {
    "symbol": "AAPL",
    "as_of": "2026-06-05T14:19:11Z",
    "freshness": "intraday",
    "market_status": "open",
    "momentum": {
      "rsi_14": 66.61,
      "rsi_zone": "neutral",
      "rsi_14_weekly": 71.17,
      "rsi_14_weekly_zone": "overbought",
      "macd": { "histogram": -0.48, "above_signal": false }
    },
    "trend_strength": { "adx_14": 45.73, "trending": true },
    "volatility": { "bollinger_20": { "percent_b": 0.76 } }
  }
}
```

The live response also carries `moving_averages` and `relative_strength`. Daily RSI is 66.6 (neutral, not yet overbought), but weekly RSI is 71.2 (overbought) and MACD has rolled below its signal line. ADX 45.7 confirms a strong trend is in force. Two calls, enough to answer.

**Final answer.** The agent answers first, then cites the data and the freshness it stood on:

> Yes, AAPL looks extended on the longer timeframe but not at a daily-chart extreme. It trades at 314.86, 1.8% below its 52-week high and at 95.3% of its 52-week range, up 54% over the past year. Weekly RSI is overbought at 71.2 and MACD has crossed below its signal line, while daily RSI is still neutral at 66.6 and ADX 45.7 shows the uptrend intact.
>
> As of 2026-06-05 14:19 UTC, market open, intraday data. Calls used: snapshot, technicals. This is context, not advice.

That last paragraph is not optional. The single instruction that produces it — answer first, cite freshness and units, never give buy/sell advice, never invent data noxstock does not return — lives in [agent instructions](/docs/agents/instructions); paste that block into your system prompt.

## Runtime A: hosted MCP [#runtime-a-hosted-mcp]

If your agent runs in Claude, Cursor, Codex, or any MCP client, connect the hosted server once and the model calls the tools directly. Setup (endpoint, auth header, smoke test) is on [MCP hosted](/docs/mcp/hosted). With it connected, the trace above is two tool calls:

```json
{ "tool": "noxstock_snapshot", "arguments": { "symbol": "AAPL" } }
{ "tool": "noxstock_technicals", "arguments": { "symbol": "AAPL" } }
```

Each tool returns the same `{ "data": ... }` envelope you saw above, unchanged. Tool arguments use native JSON types, so list-valued arguments are arrays, not comma strings — for example `noxstock_filings_list({ "symbol": "AAPL", "forms": ["10-K", "10-Q"] })`. A tool failure renders as `[CODE] message (retryable: true|false)`; branch on that string the same way you would branch on `error.retryable` over REST.

## Runtime B: REST-backed tool function [#runtime-b-rest-backed-tool-function]

If you run your own agent loop, each tool is a function that calls REST and returns the parsed `data`. The detail to get right is auth: the key goes in the `X-API-Key` header, server-side, never in a prompt or client bundle.

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="agent_tools.py"
    import os
    import httpx

    BASE = "https://api.noxstock.com"
    KEY = os.environ["NOXSTOCK_API_KEY"]

    async def nox_get(route: str, **params) -> dict:
        """One agent tool per route. Returns parsed `data` or raises on error."""
        async with httpx.AsyncClient(timeout=15) as client:
            res = await client.get(
                f"{BASE}/v2/{route}",
                params=params,
                headers={"X-API-Key": KEY},
            )
        body = res.json()
        if "error" in body:
            err = body["error"]
            raise RuntimeError(f"[{err['code']}] {err['message']} (retryable: {err['retryable']})")
        return body["data"]

    # Expose these to the model as tools:
    async def snapshot(symbol: str) -> dict:
        return await nox_get("snapshot", symbol=symbol)

    async def technicals(symbol: str) -> dict:
        return await nox_get("technicals", symbol=symbol)
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="agentTools.ts"
    const BASE = "https://api.noxstock.com";
    const KEY = process.env.NOXSTOCK_API_KEY!;

    type Envelope<T> =
      | { data: T }
      | { error: { code: string; message: string; retryable: boolean } };

    async function noxGet<T>(route: string, params: Record<string, string>): Promise<T> {
      const url = `${BASE}/v2/${route}?${new URLSearchParams(params)}`;
      const res = await fetch(url, { headers: { "X-API-Key": KEY } });
      const body = (await res.json()) as Envelope<T>;
      if ("error" in body) {
        const { code, message, retryable } = body.error;
        throw new Error(`[${code}] ${message} (retryable: ${retryable})`);
      }
      return body.data;
    }

    // Expose these to the model as tools:
    export const snapshot = (symbol: string) => noxGet("snapshot", { symbol });
    export const technicals = (symbol: string) => noxGet("technicals", { symbol });
    ```
  </Tab>
</Tabs>

The error string mirrors the MCP format on purpose: whichever runtime your agent uses, the model sees `[CODE] message (retryable: ...)` and decides the same way. Wrap `nox_get` with retry only for `retryable: true` codes — the full policy and code are in [errors and retries](/docs/guides/errors-and-retries).

## Where agents go wrong [#where-agents-go-wrong]

* Calling `fundamentals` for a valuation question. Start with `valuation`; reach for statements only when the user asks for line items.
* Calling `history` to answer "is it extended." Snapshot's `range_52w` and technicals answer it without pulling a series.
* Summarizing SEC risk from memory. Use filing section text only.
* Retrying `PLAN_UPGRADE_REQUIRED`, `SYMBOL_UNKNOWN`, or any `freshness: "unsupported"` response — none of those change on retry.
* Dropping `freshness` and `as_of` from the answer, so the reader cannot tell whether the data is intraday or a week stale.

<Card title="Agent instructions" icon="bot" href="/docs/agents/instructions">
  The full operating rules — output format, anti-advice, anti-hallucination — to paste into your system prompt.
</Card>


# Choose endpoints (/docs/guides/choose-endpoints)



Resolve a name with `/v2/search`, confirm a symbol with `/v2/coverage`, then call only the family the question needs. Most questions start at `/v2/snapshot`. This page is the table you check before writing a workflow, an agent policy, or a batch job.

## The table [#the-table]

Find the user's question, take the route plan, stop there. Every MCP tool is named `noxstock_<operation>` and takes the same arguments as native JSON (lists are arrays, not CSV) — so `GET /v2/compare?symbols=NVDA,AMD` becomes `noxstock_compare({ "symbols": ["NVDA", "AMD"] })`. The mapping is mechanical; the column below names the tool where it isn't obvious.

| User question                            | REST route plan                                                                                              | MCP tool                                            | Plan                                            |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------- |
| "What ticker is Apple?"                  | `GET /v2/search?query=apple`                                                                                 | `noxstock_search`                                   | Free                                            |
| "Can I use AAPL?"                        | `GET /v2/coverage?symbol=AAPL`                                                                               | `noxstock_coverage`                                 | Free                                            |
| "What's going on with AAPL?"             | `GET /v2/snapshot?symbol=AAPL`                                                                               | `noxstock_snapshot`                                 | Free                                            |
| "Is AAPL expensive?"                     | `GET /v2/snapshot?symbol=AAPL` then `GET /v2/valuation?symbol=AAPL`                                          | `noxstock_valuation`                                | Free                                            |
| "Show statements / margins / cash flow." | `GET /v2/fundamentals?symbol=AAPL&period=quarter`                                                            | `noxstock_fundamentals`                             | Starter                                         |
| "What does the SEC filing say?"          | `GET /v2/filings?symbol=AAPL&form=10-K,10-Q&limit=5` then `GET /v2/filings/{accession}/section/risk_factors` | `noxstock_filings_list`, `noxstock_filings_section` | Starter                                         |
| "Any insider buying or selling?"         | `GET /v2/insider?symbol=AAPL&limit=20`                                                                       | `noxstock_insider`                                  | Starter                                         |
| "Does it pay a dividend? What yield?"    | `GET /v2/snapshot` (yield is in `fundamentals_quick`) — `GET /v2/dividends` for history, growth, and health  | `noxstock_snapshot`, `noxstock_dividends`           | Free for the yield; Starter for `/v2/dividends` |
| "Is it extended / trending?"             | `GET /v2/technicals?symbol=AAPL` then `GET /v2/price-action?symbol=AAPL`                                     | `noxstock_technicals`, `noxstock_price_action`      | Starter                                         |
| "Compare NVDA, AMD, AVGO."               | `GET /v2/compare?symbols=NVDA,AMD,AVGO`                                                                      | `noxstock_compare`                                  | Starter                                         |
| "Give me the actual chart series."       | `GET /v2/history?symbol=AAPL&series=close,rsi_14&range=1y`                                                   | `noxstock_history`                                  | Starter                                         |
| "What's coming up for this symbol?"      | `GET /v2/calendar?symbol=AAPL`                                                                               | `noxstock_calendar`                                 | Starter                                         |

Free keys can call `/v2/search`, `/v2/coverage`, `/v2/snapshot`, and `/v2/valuation`. Everything else needs Starter or Builder. The route list, rate limits, and quotas live on [Plans and limits](/docs/reference/plans-and-limits) — check there, not here.

## Snapshot or valuation? [#snapshot-or-valuation]

These two answer different questions, and the difference decides whether you make one call or two.

`/v2/snapshot` is breadth: a quote, multi-window performance, the 52-week range, and a `fundamentals_quick` block with the headline multiples (`pe_ttm`, `ps_ttm`, `pb`, `peg_1y`, `ev_ebitda_ttm`, `fcf_yield_pct`). One call answers "what's going on with this stock?" including a first read on whether the multiple is high or low.

`/v2/valuation` is depth on those multiples: each one arrives as `{value, context}`, where `context` carries the 5-year median, the current percentile, and a `position` bucket (`deep_value` through `premium`). That's how you say "cheap or expensive *versus its own history*," which a bare `pe_ttm` of 33 cannot tell you.

Add the second call when the user asks whether the price is justified, not only what it is. For "is AAPL up today?" snapshot is the whole answer. For "is AAPL expensive?" you want both, and the [valuation check](/docs/guides/valuation-check) guide walks the two-call path on a Free key.

## Before you store or batch a symbol [#before-you-store-or-batch-a-symbol]

Call `/v2/coverage?symbol=` once for user-entered or stored tickers. It tells you the symbol is in the 5,119-symbol universe and which data families it supports — foreign private issuers return `unsupported` for `/v2/filings` and `/v2/insider`, and ETFs skip stock-only families. The full universe and its gaps are documented in [Coverage and gaps](/docs/reference/coverage-and-gaps); skip the check and you find the gap later, mid-answer.

## What not to reach for noxstock for [#what-not-to-reach-for-noxstock-for]

noxstock is US-equity context: quotes, performance, valuation, SEC filings, insider Form 4 activity. It does not carry trading or execution, intraday tick data, news, analyst consensus or price targets, transcripts, options, 13F ownership, ETF holdings, or non-US equities. If a prompt needs one of those, no route here answers it — say so rather than blending in a guess.

Two habits waste quota and degrade answers. Calling every family "just in case" makes an agent more likely to stitch a blended claim from fields it didn't need. And calling `/v2/fundamentals` for a valuation question, or `/v2/history` for a timing question, reaches past the route that already answers it — `/v2/valuation` and `/v2/technicals` respectively.

<Card title="Decision brief" icon="file-text" href="/docs/guides/decision-brief">
  See the coverage → snapshot → valuation path assembled into one answer.
</Card>


# Compare basket (/docs/guides/compare-basket)



Call `/v2/compare?symbols=A,B,C` to put 2–4 tickers in one scorecard, then run deeper routes on just the names worth a second look. Compare is a flat projection of snapshot and technicals fields — it ranks nothing and recommends nothing. The point is to skip three or four full snapshot calls and decide which symbols deserve them.

## Symbol count is strict [#symbol-count-is-strict]

The endpoint takes 2 to 4 symbols. One symbol is `PARAM_INVALID` (compare needs something to compare against — use `/v2/snapshot` for a single name). Five or more is `PARAM_INVALID` too; this is enforced and live-verified, not advisory. Both return HTTP 400 with the generic `PARAM_INVALID` message, which does not name the offending parameter, so validate the count yourself before the call rather than parsing the error to learn why.

## Worked example: NVDA vs AMD vs INTC [#worked-example-nvda-vs-amd-vs-intc]

Defaults give you price, 1-year return, 1-year return versus SPY, P/E, RSI, and a trend flag — enough to triage three chip names. The full response (it's small enough to show whole):

```json title="GET /v2/compare?symbols=NVDA,AMD,INTC"
{
  "data": {
    "as_of": "2026-06-05T14:19:11Z",
    "freshness": "intraday",
    "market_status": "open",
    "cache_age_seconds": 0,
    "fields_requested": [
      "price", "pct_1y", "vs_spy_pct_1y", "pe_ttm", "rsi_14", "trending"
    ],
    "symbols": [
      { "symbol": "NVDA", "price": 212.66, "pct_1y": 54.29,  "vs_spy_pct_1y": 25.78,  "pe_ttm": 33.29,   "rsi_14": 54.43, "trending": false },
      { "symbol": "AMD",  "price": 493.76, "pct_1y": 341.22, "vs_spy_pct_1y": 312.72, "pe_ttm": 170.3,   "rsi_14": 70.57, "trending": true  },
      { "symbol": "INTC", "price": 105.07, "pct_1y": 452.0,  "vs_spy_pct_1y": 423.5,  "pe_ttm": -175.91, "rsi_14": 55.31, "trending": true  }
    ],
    "fields_omitted_by_symbol": {}
  }
}
```

The MCP form is `noxstock_compare({ "symbols": ["NVDA", "AMD", "INTC"] })` — same envelope back.

Read it in two passes. `fields_requested` tells you exactly which six metrics every row carries, in order; never read a value that isn't in that list. `fields_omitted_by_symbol` is empty here, meaning all six resolved for all three names — when it isn't empty, it maps each symbol to the fields that came back unavailable, and those fields are *dropped from the row entirely* rather than set to null. An absent field is "noxstock couldn't supply this for this symbol," not zero. The scorecard:

| Symbol |  Price |    1y % | vs SPY 1y | P/E (ttm) | RSI 14 | Trending |
| ------ | -----: | ------: | --------: | --------: | -----: | -------: |
| NVDA   | 212.66 |  +54.29 |    +25.78 |     33.29 |  54.43 |       no |
| AMD    | 493.76 | +341.22 |   +312.72 |    170.30 |  70.57 |      yes |
| INTC   | 105.07 | +452.00 |    +423.5 |   -175.91 |  55.31 |      yes |

The honest one-liner from this data:

> Over the past year INTC (+452%) and AMD (+341%) crushed NVDA (+54%) and both still register as trending; NVDA carries by far the lowest P/E (33.29), AMD the richest (170.3), and INTC's is negative (-175.91) because it's loss-making on a trailing basis, so P/E isn't a valuation read for it. AMD's RSI of 70.57 is at the overbought threshold. As of 2026-06-05T14:19:11Z, intraday, market open.

That's a description, not a pick. The negative INTC P/E is the kind of value you must carry through verbatim rather than smooth over: it signals trailing losses, and silently dropping the sign would invent a profitable company.

## Fields and defaults [#fields-and-defaults]

Omit `fields` and you get the six defaults above: `price`, `pct_1y`, `vs_spy_pct_1y`, `pe_ttm`, `rsi_14`, `trending`. Pass `fields=` (CSV in REST, an array in MCP) to request any subset of these 23:

`price`, `pct_1d`, `pct_1m`, `pct_ytd`, `pct_1y`, `vs_spy_pct_1y`, `range_52w_position_pct`, `drawdown_from_high_pct`, `market_cap_usd`, `pe_ttm`, `ps_ttm`, `pb`, `peg_1y`, `ev_ebitda_ttm`, `fcf_yield_pct`, `dividend_yield_pct`, `beta_1y`, `rsi_14`, `rsi_zone`, `trending`, `golden_cross_active`, `vs_sma_200_pct`, `distance_from_52w_high_pct`.

ETFs in a basket omit the stock-only fields (`market_cap_usd`, `pe_ttm`, and the rest), which then show up under `fields_omitted_by_symbol` for that ticker. That's expected, not a failure.

## Then deepen the finalists [#then-deepen-the-finalists]

Compare narrows the field; it doesn't settle it. The mistake is calling snapshot, valuation, fundamentals, and insider for all four names *before* the scorecard — that's the work compare exists to defer. Once two names are left, run the full read on just those. For "which is more reasonably priced?", the [valuation check](/docs/guides/valuation-check) gives each survivor its multiples against five years of its own history — the context the flat `pe_ttm` in this scorecard can't.

<Card title="Valuation check" icon="gauge" href="/docs/guides/valuation-check">
  Take a finalist's P/E and read it against its own 5-year distribution.
</Card>


# Decision brief (/docs/guides/decision-brief)



A decision brief is the context a user needs to think about one symbol, with none of the trade advice. The spine is `/v2/coverage` → `/v2/snapshot` → `/v2/valuation`, all on the Free plan; add `/v2/filings` or `/v2/insider` only when the prompt asks for primary-source risk or insider activity. This is a context product, not an advisor: report what the data says, never tell the user to buy, sell, hold, or size anything.

This page walks one filled brief end to end. The reusable answer templates — the bullet skeletons you'd paste into an agent — live in [agent recipes](/docs/agents/recipes); this guide is the worked example that shows why each line is there.

## The spine [#the-spine]

```text
GET /v2/coverage?symbol=AAPL    # confirm support + asset_type, once
GET /v2/snapshot?symbol=AAPL    # quote, performance, 52w range, fundamentals_quick
GET /v2/valuation?symbol=AAPL   # multiples vs 5-year history
```

Coverage is the cheap insurance call: it tells you the symbol is in the universe and which families it supports before you build on data that might be `unsupported`. Snapshot and valuation are the brief's body. For a plain "give me a brief," those three are the whole job — `/v2/fundamentals`, `/v2/filings`, and `/v2/insider` are depth you add on request, not by default. The route selection rationale is owned by [Choose endpoints](/docs/guides/choose-endpoints); this page just uses it.

## Worked example: a brief on AAPL [#worked-example-a-brief-on-aapl]

The prompt: &#x2A;"Quick brief on Apple, and is there any unusual insider selling?"* That second clause earns the optional `/v2/insider` call. Two fixtures drive the answer below.

From `/v2/snapshot?symbol=AAPL` (quote, performance, and range shown; the live response also returns the full `fundamentals_quick` block, `sector`, and `industry`):

```json title="GET /v2/snapshot?symbol=AAPL — trimmed"
{
  "data": {
    "symbol": "AAPL",
    "as_of": "2026-06-05T14:19:06Z",
    "freshness": "intraday",
    "market_status": "open",
    "quote": { "price": 314.86, "change_pct": 1.17, "previous_close": 311.23 },
    "performance": { "pct_1m": 9.62, "pct_ytd": 15.06, "pct_1y": 54.06, "vs_spy_pct_1y": 25.56 },
    "range_52w": { "high": 316.94, "low": 194.3, "position_pct": 95.3, "drawdown_from_high_pct": -1.8 },
    "fundamentals_quick": { "pe_ttm": 37.28, "fcf_yield_pct": 2.83, "dividend_yield_pct": 0.34 }
  }
}
```

From `/v2/insider?symbol=AAPL` (the 90-day rollup; the live response also returns up to 10 `recent_transactions`):

```json title="GET /v2/insider?symbol=AAPL — summary, trimmed"
{
  "data": {
    "symbol": "AAPL",
    "as_of": "2026-06-05T06:45:45Z",
    "freshness": "end_of_day",
    "cache_age_seconds": 27207,
    "summary_90d": {
      "market_activity": {
        "buy_count": 0,
        "sell_count": 13,
        "net_value_usd": -111705105.08,
        "net_direction": "selling"
      },
      "unique_insiders": 7,
      "notices": ["recent_transactions_limited_to_10"]
    }
  }
}
```

In MCP these are `noxstock_snapshot({ "symbol": "AAPL" })` and `noxstock_insider({ "symbol": "AAPL" })`; the envelopes match the REST responses exactly.

### The brief this supports [#the-brief-this-supports]

Answer first, then the facts, then a freshness line that's honest about the two routes having different ages, then the calls used:

> **Apple is trading near its 52-week high after a strong year, and insiders have been net sellers over the past 90 days.** At 314.86 (+1.17% on the day) it sits at the 95th percentile of its 52-week range, 1.8% off the high of 316.94. It's up 54.06% over the year — 25.56 points ahead of SPY — and 15.06% year to date, on a trailing P/E of 37.28 with a 2.83% free-cash-flow yield and a 0.34% dividend.
>
> On insiders: over the trailing 90 days there were 13 open-market sales and zero buys across 7 insiders, for net selling of about -$111.7M. That's directional selling, but it's routine for a mega-cap and says nothing about price on its own.
>
> Freshness: snapshot intraday, as\_of 2026-06-05T14:19:06Z, market open. Insider rollup end\_of\_day, as\_of 2026-06-05T06:45:45Z (about 7.5 hours old) — Form 4 data settles overnight, so it lags the quote by design.
>
> Calls used: /v2/snapshot, /v2/insider.

Three things make that a good brief, not a generated one:

* **The freshness line carries both timestamps.** The quote is intraday and live; the insider rollup is `end_of_day` with `cache_age_seconds` of 27207 (\~7.5 hours). Collapsing them into one "current as of now" would misrepresent the older half. Cite each route's own `freshness` and `as_of`. The enum and how to detect it are owned by [the freshness reference](/docs/reference/freshness).
* **The negative net value keeps its sign and its caveat.** `net_value_usd` is `-111705105.08`; it's net *selling*, and the brief says so while flagging that mega-cap insider sales are routine. Dropping the sign or the caveat would both mislead.
* **The truncation notice is respected.** `notices: ["recent_transactions_limited_to_10"]` means the detail list is capped at 10; the 90-day *summary* still aggregates the latest 200 Form 4 filings, so the rollup counts are complete even though the line items aren't. Don't quote "13 sales" as if it were the full picture if the user wants every transaction — point them at the cap.

## When the data says "no answer" [#when-the-data-says-no-answer]

If coverage flags a family as `unsupported` — a foreign private issuer for `/v2/filings` and `/v2/insider`, or an ETF for valuation — the brief states that the data isn't available for that symbol and stops. It does not substitute a guess, and it does not retry an `unsupported` response as if it were an outage. A brief that admits a gap is more useful than one that fills it with invention.

<Card title="Agent recipes" icon="bot" href="/docs/agents/recipes">
  The reusable brief and answer templates to drop into an agent.
</Card>


# Errors and retries (/docs/guides/errors-and-retries)



Every noxstock response is either `{ "data": ... }` or `{ "error": { "code", "message", "retryable" } }`. Read `error.retryable` and do exactly what it says: retry when it is `true`, surface the fix when it is `false`. Do not infer recovery from the HTTP status alone, and never retry an `unsupported` data state — that is a `200` with real data, not an error.

## Retry policy [#retry-policy]

This table is the whole decision. `retryable` comes straight off the envelope; the HTTP status is for logging, not branching.

| Code                        | HTTP | Retry? | What to do                                                                    |
| --------------------------- | ---: | ------ | ----------------------------------------------------------------------------- |
| `UNAUTHORIZED`              |  401 | No     | Fix the `X-API-Key` header; recreate the key if it was revoked.               |
| `PLAN_UPGRADE_REQUIRED`     |  403 | No     | The route needs Starter or Builder; stay on Free routes or upgrade.           |
| `SYMBOL_INVALID`            |  400 | No     | Fix the ticker format (`^[A-Z0-9-]{1,8}$`, e.g. `BRK-B`).                     |
| `SYMBOL_UNKNOWN`            |  404 | No     | Resolve the name with `/v2/search` first; the symbol is outside the universe. |
| `PARAM_INVALID`             |  400 | No     | Fix params. The message is generic and does not name the bad field.           |
| `RATE_LIMITED`              |  429 | Yes    | Wait the `Retry-After` seconds, then resume slower.                           |
| `UPSTREAM_UNAVAILABLE`      |  503 | Yes    | Retry with backoff; a cold SEC path may need a loading state.                 |
| `AUTH_UPSTREAM_UNAVAILABLE` |  503 | Yes    | Retry shortly; sends `Retry-After: 5`.                                        |
| `PREREQUISITE_MISSING`      |  409 | No     | MCP resources only — never returned by a REST endpoint.                       |

`PARAM_INVALID` is the one that bites: the message is the literal string `"Invalid request parameters."`, so log the request you sent rather than waiting for the API to tell you which param was wrong. The [error codes reference](/docs/reference/error-codes) carries the exact message strings.

## The 429 envelope [#the-429-envelope]

A rate-limited response pairs the retryable error body with headers that tell you exactly how long to wait. This is the live fixture:

```http title="HTTP/1.1 429 Too Many Requests"
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1780669200
Retry-After: 21
```

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow request rate and retry.",
    "retryable": true
  }
}
```

`Retry-After` is in seconds (21 here). Sleep at least that long before the next request for that key — sending sooner earns another 429.

## A retry loop that obeys its own rules [#a-retry-loop-that-obeys-its-own-rules]

The loop has to do four things the table implies: retry only on `retryable: true`, prefer the `Retry-After` header over a guessed backoff, cap total attempts so a persistent outage fails fast, and cap total wait so you never sleep for hours. The wait budget must cover a full minute window — a minute-bucket 429 can send `Retry-After` of up to 60 seconds, so a 30-second budget would give up on a limit that was about to clear. Below, three attempts and a 90-second ceiling.

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="retry.py"
    import asyncio
    import httpx

    async def get_with_retry(
        client: httpx.AsyncClient,
        url: str,
        api_key: str,
        max_attempts: int = 3,
        max_total_wait: float = 90.0,
    ) -> dict:
        waited = 0.0
        for attempt in range(1, max_attempts + 1):
            res = await client.get(url, headers={"X-API-Key": api_key})
            body = res.json()

            if "data" in body:
                return body["data"]

            err = body["error"]
            retryable = err["retryable"]
            if not retryable or attempt == max_attempts:
                raise RuntimeError(f"[{err['code']}] {err['message']}")

            # Prefer the server's Retry-After; fall back to exponential backoff.
            retry_after = res.headers.get("Retry-After")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 8)
            if waited + delay > max_total_wait:
                raise RuntimeError(f"[{err['code']}] wait budget exhausted")
            waited += delay
            await asyncio.sleep(delay)

        raise RuntimeError("retry loop exhausted")
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="retry.ts"
    type Envelope<T> =
      | { data: T }
      | { error: { code: string; message: string; retryable: boolean } };

    const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

    export async function getWithRetry<T>(
      url: string,
      apiKey: string,
      maxAttempts = 3,
      maxTotalWaitMs = 90_000,
    ): Promise<T> {
      let waited = 0;
      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        const res = await fetch(url, { headers: { "X-API-Key": apiKey } });
        const body = (await res.json()) as Envelope<T>;

        if ("data" in body) return body.data;

        const { code, message, retryable } = body.error;
        if (!retryable || attempt === maxAttempts) {
          throw new Error(`[${code}] ${message}`);
        }

        // Prefer the server's Retry-After; fall back to exponential backoff.
        const retryAfter = res.headers.get("Retry-After");
        const delayMs = retryAfter ? Number(retryAfter) * 1000 : Math.min(2 ** attempt, 8) * 1000;
        if (waited + delayMs > maxTotalWaitMs) {
          throw new Error(`[${code}] wait budget exhausted`);
        }
        waited += delayMs;
        await sleep(delayMs);
      }
      throw new Error("retry loop exhausted");
    }
    ```
  </Tab>
</Tabs>

The budget guard is also your quota protection. When a `429` comes from the plan quota rather than the minute bucket — Free's daily 100, paid monthly quotas — `Retry-After` is the time to the window reset and can be **hours** (a Free daily 429 sends roughly the seconds until midnight UTC). The loop above correctly refuses to sleep that long and fails fast with `wait budget exhausted`; treat that as "stop the job and surface it", not as an error to swallow. [Plans and limits](/docs/reference/plans-and-limits) covers how the two windows show up in the headers.

The same loop works behind an MCP client: a tool failure renders as `[CODE] message (retryable: true|false)`, so parse the `retryable` flag out of that string and branch identically. `PREREQUISITE_MISSING` only appears on MCP resources and is never retryable — fetch the resource's prerequisite first instead of looping.

## Where this goes wrong [#where-this-goes-wrong]

* Parsing a success as a raw object instead of reaching into `{ data }`.
* Retrying `UNAUTHORIZED` with the same revoked key, or treating `PLAN_UPGRADE_REQUIRED` as an outage.
* Retrying `freshness: "unsupported"` — it is a stable `200`, not a transient failure.
* Ignoring `Retry-After` and hammering the same key into a second 429.
* Retrying forever. Without an attempt cap, a real upstream outage turns one slow request into a hung worker.

<Card title="Production patterns" icon="activity" href="/docs/guides/production-patterns">
  Drop this retry loop into a cached, key-safe client.
</Card>


# Insider scan (/docs/guides/insider-scan)



`/v2/insider` returns one trailing-90-day rollup plus the most recent transaction rows. The work is reading two summaries correctly: `market_activity` is the open-market buy/sell signal, and `all_activity` is every Form 4 kind including exercises and gifts. Mix them up and a quiet quarter looks like a sell-off.

## One call [#one-call]

```python title="insider.py"
import httpx

r = httpx.get(
    "https://api.noxstock.com/v2/insider",
    params={"symbol": "AAPL", "limit": 10},  # limit 1-200, default 10
    headers={"X-API-Key": "nxs_..."},
)
data = r.json()["data"]
summary = data["summary_90d"]
```

The rollup scans the latest 200 Form 4 filings in the trailing 90 days. `limit` only caps how many `recent_transactions` rows come back — it does not change the summary math.

## The summary, from a live AAPL response [#the-summary-from-a-live-aapl-response]

```json title="insider.data.summary_90d"
{
  "market_activity": {
    "buy_count": 0,
    "sell_count": 13,
    "net_shares_market_only": -397759,
    "net_value_usd": -111705105.08,
    "net_direction": "selling"
  },
  "all_activity": {
    "transactions": 43,
    "net_shares_all_kinds": 25895,
    "transactions_by_kind": {
      "open_market_sale": 13,
      "derivative_exercise": 22,
      "tax_withholding": 6,
      "gift": 2
    }
  },
  "unique_insiders": 7,
  "officer_share_pct": 42,
  "director_share_pct": 12,
  "ten_b5_1_plan_ratio_pct": 0,
  "notices": ["recent_transactions_limited_to_10"]
}
```

Read it straight:

* **Open-market:** 0 buys, 13 sells, net -397,759 shares worth -$111.7M. `net_direction` is `selling`. These are the cash trades insiders chose to make — the part most people mean by "insider selling."
* **All Form 4 activity:** 43 transactions across 7 insiders. Of those, only 13 are open-market sales; the other 30 are 22 derivative exercises, 6 tax-withholding events, and 2 gifts. `net_shares_all_kinds` is *positive* (+25,895) because exercises add shares — which is why you never quote the all-activity net as a sell figure.
* **10b5-1:** `ten_b5_1_plan_ratio_pct` is 0. None of the open-market sales ran through a pre-scheduled 10b5-1 plan, so they are discretionary rather than calendar-driven. Plan sales carry less signal because they were set up in advance; a 0% ratio means these were not.

## Recent rows [#recent-rows]

Each row carries a `transaction_code` (the raw Form 4 code: `S` sale, `G` gift, `M` exercise, `F` tax withholding) and a plain-English `transaction_kind`. Two rows from the live response:

```json title="insider.data.recent_transactions[0..2] (trimmed)"
[
  {
    "filing_date": "2026-05-29",
    "transaction_date": "2026-05-27",
    "insider_name": "Arthur D Levinson",
    "insider_role": "Director",
    "transaction_code": "S",
    "transaction_kind": "open_market_sale",
    "shares": 50000,
    "price_per_share": 311.02,
    "value_usd": 15551000.0,
    "shares_remaining": 3764576,
    "ten_b5_1": false,
    "accession": "0001140361-26-023363"
  },
  {
    "filing_date": "2026-05-29",
    "transaction_date": "2026-05-27",
    "insider_name": "Arthur D Levinson",
    "insider_role": "Director",
    "transaction_code": "G",
    "transaction_kind": "gift",
    "shares": 65000,
    "price_per_share": { "available": false, "reason": "gift_no_market_price" },
    "value_usd": { "available": false, "reason": "gift_no_market_price" },
    "shares_remaining": 3764576,
    "ten_b5_1": false,
    "accession": "0001140361-26-023363"
  }
]
```

The live response returns 10 rows here (the `limit` default). On the gift row, `price_per_share` and `value_usd` are objects with `available: false` and a `reason` — a gift has no market price. Treat that as "no dollar figure," never as a $0 trade. Exercises (`derivative_exercise_price_not_disclosed`) and tax withholding (`tax_withholding_no_market_price`) carry the same shape.

## Notices [#notices]

`summary_90d.notices` flags anything that bounds the rollup. Two you will see:

* `recent_transactions_limited_to_N` — more rows exist than the `limit` you asked for; raise `limit` (up to 200) to see them.
* `scanned_latest_200_filings_only` — the 90-day window held more than 200 Form 4 filings, so the rollup covers the most recent 200. Surface this; the summary is complete only up to that cap.

Pass `notices` through to the reader verbatim. Dropping it hides the boundary on the numbers.

## A reportable answer [#a-reportable-answer]

```text title="answer"
AAPL insider activity, trailing 90 days (as_of 2026-06-05, end_of_day):
- Open-market: 0 buys, 13 sells, net -$111.7M across 7 insiders. Direction: selling.
- None of the sales were 10b5-1 plan sales (0% plan ratio).
- The other 30 Form 4 events were option exercises, tax withholding, and gifts —
  routine, not open-market trades.

This is a description of filed activity, not a buy or sell signal.
```

That last line is the guardrail. Net selling is not "bearish," net buying is not "bullish" — insiders sell for taxes, diversification, and scheduled plans. Describe the activity and its sign; do not convert it to advice. That anti-advice rule lives in the [agent instructions](/docs/agents/instructions).

## Scope [#scope]

* Form 4 only. Institutional ownership and 13F holders are not in noxstock today.
* ETFs and the 926 foreign private issuers that file 20-F/40-F/6-K return `unsupported` here — there are no domestic Form 4 filers to scan. See [coverage and gaps](/docs/reference/coverage-and-gaps).

<Card title="SEC risk review" icon="file-text" href="/docs/guides/sec-risk-review">
  For the prose of a filing — risk factors, MD\&A — walk the section endpoints instead.
</Card>


# Production patterns (/docs/guides/production-patterns)



Two things separate a toy integration from a production one: you cache by how fast each data family actually moves, and you keep the key out of anything a user can see. Everything else — retries, quotas — links out to the page that owns it.

## Keep the key server-side [#keep-the-key-server-side]

The `X-API-Key` secret belongs in your backend, an agent runtime config, or a secret manager. Never anywhere a user or a model can read it.

* No `NOXSTOCK_API_KEY` in a browser bundle, mobile app, public repo, prompt, log line, or screenshot.
* Proxy client calls through your own backend; the key never reaches the browser.
* The raw secret is shown once at creation. Store it in a secret manager, not a config file you commit. New keys come from the [dashboard](https://noxstock.com/dashboard/keys).
* On suspected leak, recreate the key and swap it in. Revocation takes effect within about a minute.
* Do not cache `UNAUTHORIZED` or `PLAN_UPGRADE_REQUIRED` responses as if they were data — a fixed key or upgrade should take effect immediately.

## Cache by data family [#cache-by-data-family]

A snapshot during market hours goes stale in seconds; a 10-K section never changes. Cache each family on its own clock. These are starting points to tune against your traffic, not API contracts:

| Data family                                  | Suggested cache                                           |
| -------------------------------------------- | --------------------------------------------------------- |
| Search and coverage                          | Hours to days                                             |
| Snapshot during market hours                 | 30–120 seconds                                            |
| Snapshot after close                         | 5–30 minutes                                              |
| Valuation, fundamentals, earnings, dividends | 1–24 hours                                                |
| Technicals, price action, history            | 5–30 minutes for active views; longer for offline reports |
| Filing metadata and section text             | Days to indefinite                                        |
| Insider activity                             | 1–24 hours                                                |
| Calendar                                     | 1–24 hours                                                |

Two hooks make these TTLs self-tuning. Every payload carries `cache_age_seconds` (0 means freshly computed), so you can see how warm the served data already was. And every response carries `freshness` — if it comes back `stale` or `degraded`, shorten your own TTL or show the caveat rather than caching it long.

### Cache keys [#cache-keys]

Key by route plus normalized params. A snapshot key is as simple as:

```text
nox:snapshot:AAPL
```

Normalize before you build the key: uppercase the symbol, sort multi-value params (`series`, `forms`, `fields`), and apply defaults so `range=1y` and an omitted range hit the same entry. A history key with sorted series looks like `nox:history:AAPL:range=1y:series=close,rsi_14`.

<Note>
  If two plans or keys can see different data or quotas, scope the key — `nox:snapshot:AAPL:builder` or a per-key hash. A shared cache that ignores plan scope can serve a Free-route miss as a hit, or leak one tenant's warmer data to another.
</Note>

## Retries and rate limits [#retries-and-rate-limits]

Wrap every call in the retry loop that honors `Retry-After`, caps attempts, and retries only `retryable: true`. The code lives in [errors and retries](/docs/guides/errors-and-retries) — use it directly rather than reimplementing it here.

Every authenticated response carries `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix epoch seconds); watch `Remaining` to back off before you hit a 429. The per-plan minute and quota numbers live on [plans and limits](/docs/reference/plans-and-limits).

## SEC routes need a loading state [#sec-routes-need-a-loading-state]

Filing and insider routes read from EDGAR. A cold fetch for a heavy filer can be slow, so do not block a page render on it. Run those routes in a background job or behind a loading state, and cache the result hard — filing section text is effectively immutable.

```text
GET /v2/filings?symbol=AAPL&form=10-K,10-Q&limit=5
GET /v2/filings/{accession}
GET /v2/filings/{accession}/section/risk_factors
```

## Preserve the honest fields [#preserve-the-honest-fields]

Whatever your UI shows, carry these through from the response so the answer stays truthful:

* `freshness`, `as_of`, `market_status`, and `cache_age_seconds`.
* `reason` and `available: false` on unsupported families, `fields_omitted_by_symbol` from compare, and `summary_90d.notices` from insider rollups.
* Units and signs: `_usd`, `_pct`, share counts, drawdowns, cash-flow signs, insider net values.

Hiding a `stale`, `degraded`, or `unsupported` state makes the number look more certain than it is. Surface it.

<CardGroup cols="2">
  <Card title="Batch workflows" icon="layers" href="/docs/guides/batch-workflows">
    Run many symbols with bounded concurrency and no bulk endpoint.
  </Card>

  <Card title="Plans and limits" icon="gauge" href="/docs/reference/plans-and-limits">
    Per-plan minute limits, monthly quotas, and route gating.
  </Card>
</CardGroup>


# SEC risk review (/docs/guides/sec-risk-review)



Reading a 10-K risk section is a three-call walk: list filings, pick the accession, fetch one section. You never download the whole filing, and you summarize from the text the section endpoint returns — nothing from news, memory, or consensus gets blended in.

## The walk [#the-walk]

<Steps>
  <Step>
    List periodic filings and choose the form you actually want.
  </Step>

  <Step>
    Read the section index on the chosen accession to see which sections exist and how large they are.
  </Step>

  <Step>
    Fetch one section by name and summarize from that text.
  </Step>
</Steps>

## 1. List filings, pick the accession [#1-list-filings-pick-the-accession]

`/v2/filings` defaults to `form=10-K,10-Q,8-K` and `limit=20`. Pass a tighter `form` CSV when you only want the annual report. Here, `form=10-K` returns just the 10-K rows for AAPL.

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="list_filings.py"
    import httpx

    r = httpx.get(
        "https://api.noxstock.com/v2/filings",
        params={"symbol": "AAPL", "form": "10-K", "limit": 5},
        headers={"X-API-Key": "nxs_..."},
    )
    filings = r.json()["data"]["filings"]
    latest = filings[0]          # rows come back newest-first
    accession = latest["accession"]
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript title="listFilings.ts"
    const res = await fetch(
      "https://api.noxstock.com/v2/filings?symbol=AAPL&form=10-K&limit=5",
      { headers: { "X-API-Key": "nxs_..." } },
    );
    const { data } = await res.json();
    const latest = data.filings[0]; // rows come back newest-first
    const accession = latest.accession;
    ```
  </Tab>
</Tabs>

The latest 10-K row, copied from the live response (the full list also carries 10-Q and 8-K rows when you widen `form`):

```json title="filings.data.filings[…] (one row)"
{
  "accession": "0000320193-25-000079",
  "form": "10-K",
  "filing_date": "2025-10-31",
  "period_of_report": "2025-09-27",
  "items": [],
  "items_text": [],
  "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm",
  "size_bytes": 9392337,
  "sections": []
}
```

That `size_bytes` is 9.4 MB. You are not going to read it whole — `sections` is empty on the list because the index lives on the next call.

<Note>
  If the user asks for "the latest periodic filing" rather than the 10-K specifically, request `form=10-K,10-Q`, then pick by `filing_date` and tell the reader which form you used. Calling something "the latest 10-K" after selecting a 10-Q is the most common reporting error here.
</Note>

## 2. Read the section index [#2-read-the-section-index]

`GET /v2/filings/0000320193-25-000079` returns the section index with a `char_count` per section. That count is your budget — it tells you how much text the next call will return before you spend it.

```json title="filing-10k.data (trimmed)"
{
  "symbol": "AAPL",
  "symbol_status": { "resolved": true },
  "accession": "0000320193-25-000079",
  "form": "10-K",
  "filing_date": "2025-10-31",
  "period_of_report": "2025-09-27",
  "sections": [
    { "name": "business", "char_count": 16004 },
    { "name": "risk_factors", "char_count": 68069 },
    { "name": "mda", "char_count": 21009 }
  ]
}
```

Section names you will see on periodic filings: `business`, `risk_factors`, `mda`, and on some filings `quantitative_qualitative_disclosures` and `controls_and_procedures`. The section list is per-filing, not guaranteed — check `sections[].name` before requesting one.

8-K metadata has a different shape: no `sections` array at all. Instead it carries `items` (the disclosed item codes with titles, e.g. `2.02 — Results of Operations`) and a `press_release` object with `available` and `char_count`. When `press_release.available` is true, fetch it with `/section/press_release`; the `risk_factors`-style names do not exist on an 8-K. `items` and `items_text` on list rows are 8-K item codes too — empty arrays on 10-K/10-Q rows. Form 4 metadata carries neither sections nor items, just the filing facts; its `period_of_report` is usually populated but can be null.

The accession routes accept an optional `?symbol=` cross-check. `GET /v2/filings/0000320193-25-000079?symbol=AAPL` confirms the accession belongs to AAPL; a mismatch returns `PARAM_INVALID`. A well-formed accession that matches no filing returns 200 with `symbol_status` `{ "resolved": false, "reason": "symbol_unresolved_from_accession" }`; a malformed accession is a 400. See [error codes](/docs/reference/error-codes) for the full set.

## 3. Fetch one section [#3-fetch-one-section]

`GET /v2/filings/0000320193-25-000079/section/risk_factors` returns the text and echoes the same `char_count`. Fetch only the section you intend to read.

```json title="filing-section-risk-factors.data (text trimmed)"
{
  "symbol": "AAPL",
  "accession": "0000320193-25-000079",
  "form": "10-K",
  "section": "risk_factors",
  "char_count": 68069,
  "text": "Item 1A.    Risk Factors\nThe following summarizes factors that could have a material adverse effect on the Company's business... Macroeconomic and Industry Risks... Beginning in the second quarter of 2025, new tariffs were announced on imports to the U.S. ...",
  "freshness": "intraday",
  "market_status": "open",
  "cache_age_seconds": 12,
  "available": true
}
```

The `text` above is trimmed for the page; the live response returns the full 68,069 characters. Summarize from that text and nothing else.

A risk summary built only from this section:

```text title="answer"
Top risks in Apple's FY2025 10-K (filed 2025-10-31, risk_factors)
- Tariffs: new U.S. tariffs from Q2 2025 on China, India, Japan, South Korea,
  Taiwan, Vietnam, and the EU, plus a Section 232 semiconductor investigation;
  impact described as uncertain.
- Supply concentration: manufacturing is heavily outsourced to a small set of
  Asian partners, with single-source components.
- Antitrust and the DOJ/Google search case, where remedies on appeal could
  materially affect the search licensing revenue Apple earns from Google.

Source: accession 0000320193-25-000079, section risk_factors,
as_of 2026-06-05T14:19:24Z, freshness intraday.
```

Every bullet traces to a sentence in the returned `text`. That is the guardrail: a SEC risk summary is a summary of one section's words. Do not add a headline, an analyst note, a price reaction, or a remembered fact — if it is not in the section text, it does not go in the answer. This is the anti-hallucination rule from the [agent instructions](/docs/agents/instructions), applied to filings.

## MCP shape [#mcp-shape]

The hosted tools take the same walk, with one argument difference: REST `form` is a CSV string, but the MCP `forms` argument is a JSON array.

```json
noxstock_filings_list({ "symbol": "AAPL", "forms": ["10-K"], "limit": 5 })
noxstock_filings_get({ "accession": "0000320193-25-000079" })
noxstock_filings_section({ "accession": "0000320193-25-000079", "name": "risk_factors" })
```

## Cold first call [#cold-first-call]

The first read of an accession pulls from EDGAR and can take up to \~20 seconds for a large 10-K; repeat reads of the same accession return in well under a second. Listing filings is fast either way — the cold cost is per accession. Don't block a whole UI on it — see [coverage and gaps](/docs/reference/coverage-and-gaps) for the latency note. Filing and insider data are also `unsupported` for the 926 foreign private issuers that file 20-F/40-F/6-K, and for ETFs; the row will carry a machine-readable reason rather than text.

<Card title="Insider scan" icon="search" href="/docs/guides/insider-scan">
  Form 4 activity is a separate endpoint with its own rollup — not a filing section.
</Card>


# Technical timing check (/docs/guides/technical-timing)



"Is AAPL extended?" is a two-call question: `/v2/technicals` gives the indicator read, `/v2/price-action` gives the range-and-volume context. Both are precomputed, so you do not pull `/v2/history` to answer it — history is for when the user wants the actual rows.

## Two calls [#two-calls]

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="timing.py"
    import httpx

    h = {"X-API-Key": "nxs_..."}
    tech = httpx.get("https://api.noxstock.com/v2/technicals",
                     params={"symbol": "AAPL"}, headers=h).json()["data"]
    pa = httpx.get("https://api.noxstock.com/v2/price-action",
                   params={"symbol": "AAPL"}, headers=h).json()["data"]
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript title="timing.ts"
    const h = { "X-API-Key": "nxs_..." };
    const tech = (await (await fetch(
      "https://api.noxstock.com/v2/technicals?symbol=AAPL", { headers: h })).json()).data;
    const pa = (await (await fetch(
      "https://api.noxstock.com/v2/price-action?symbol=AAPL", { headers: h })).json()).data;
    ```
  </Tab>
</Tabs>

## The technical read [#the-technical-read]

Trimmed from a live AAPL response — the fields that answer "extended?":

```json title="technicals.data (trimmed)"
{
  "moving_averages": {
    "sma_50": 279.99,
    "sma_200": 264.38,
    "vs_sma_50_pct": 11.16,
    "vs_sma_200_pct": 17.72,
    "golden_cross_active": true,
    "distance_from_52w_high_pct": -1.8
  },
  "momentum": {
    "rsi_14": 66.61,
    "rsi_zone": "neutral",
    "rsi_14_weekly": 71.17,
    "rsi_14_weekly_zone": "overbought",
    "stochastic_14_3_3": { "k": 80.87, "d": 80.08, "zone": "overbought" },
    "macd": { "value": 9.2, "signal_line": 9.68, "histogram": -0.48, "above_signal": false }
  },
  "trend_strength": { "adx_14": 45.73, "trending": true, "obv_trend_30d": "up" },
  "volatility": { "bollinger_20": { "percent_b": 0.76 }, "beta_1y": 0.96 }
}
```

How to read each piece:

* **`rsi_zone`** is the daily RSI bucket. In this fixture daily `rsi_14` is 66.61, zone `neutral`; the weekly `rsi_14_weekly` is 71.17, zone `overbought`. The zone enum you will see across symbols: `oversold`, `neutral`, `overbought`. Daily and weekly can disagree — report both rather than collapsing them.
* **`golden_cross_active: true`** means the 50-day SMA sits above the 200-day. Combined with `adx_14` of 45.73 and `trending: true`, the trend is strong and intact.
* **`distance_from_52w_high_pct: -1.8`** puts price 1.8% under the 52-week high — near the top of its range.
* **`percent_b: 0.76`** places price at 76% of the way up the 20-day Bollinger band: elevated, not pinned to the upper band.

## The price-action context [#the-price-action-context]

```json title="price-action.data (trimmed)"
{
  "volume": { "latest": 44869134, "avg_30d": 48146449, "ratio_to_avg": 0.93 },
  "recent_extremes": {
    "high_90d": { "value": 316.94, "date": "2026-06-03" },
    "low_90d": { "value": 245.28, "date": "2026-03-30" }
  },
  "streaks": { "direction": "none", "consecutive_days": 0, "biggest_down_day_1y_pct": -5.0 },
  "drawdowns": { "max_90d": { "pct": -11.24 }, "max_1y": { "pct": -13.8 } }
}
```

`ratio_to_avg` of 0.93 says volume is slightly below its 30-day average — the move up is not on a volume spike. The 90-day drawdown of -11.24% (keep the sign) shows the recent low was a real dip, not a straight line up. No active streak.

## The answer they support [#the-answer-they-support]

```text title="answer (3 lines)"
AAPL is mildly extended, not stretched. Daily RSI is neutral (66.6) but weekly is
overbought (71.2); price sits 1.8% below its 52-week high at Bollinger %B 0.76.
The uptrend is strong and intact (golden cross, ADX 45.7) on below-average volume.
```

Every clause traces to a field above. That is the whole job: read the precomputed indicators, weigh daily against weekly, keep the signs, and stop.

<Note>
  `market_status` (`open` here) is a session flag — whether regular trading hours are in effect. It is not an execution signal or an exchange feed; do not imply order timing from it. See [freshness](/docs/reference/freshness) for `market_status`, `as_of`, and the `degraded` state newer listings can return.
</Note>

## When you actually need the series [#when-you-actually-need-the-series]

If the question needs rows — to draw a chart, or feed a model — call [`/v2/history`](/docs/api-reference/endpoints/market-context/history): `series` is a CSV of up to 3 (e.g. `close,rsi_14`), `range` defaults to `1y`. Don't reach for it to answer "extended?" — technicals and price-action already hold the indicator, range, volume, streak, and drawdown context.

<Card title="Compare basket" icon="columns-3" href="/docs/guides/compare-basket">
  To put these technical fields side by side across 2-4 symbols, use compare.
</Card>


# Valuation check (/docs/guides/valuation-check)



Call `/v2/snapshot` for the headline multiples, then `/v2/valuation` for the 5-year context that tells you whether those multiples are high or low for *this* stock. Both routes are on the Free plan, so the full check costs two calls and no upgrade. Don't reach for `/v2/fundamentals` here — that answers "why," and most valuation prompts only ask "how much."

## The `{value, context}` pattern [#the-value-context-pattern]

`/v2/snapshot` already returns `pe_ttm`, `ps_ttm`, and friends in its `fundamentals_quick` block. A raw `pe_ttm` of 33 is not yet an answer — 33 is cheap for some names and rich for others. `/v2/valuation` fixes that by wrapping every multiple as `{value, context}`:

```json
"pe_ttm": {
  "value": 33.29,
  "context": {
    "available": true,
    "median_5y": 57.67,
    "percentile_5y": 2.0,
    "position": "deep_value",
    "coverage_pct": 97
  }
}
```

`value` is the current multiple. `context.median_5y` is the trailing-5-year median of that same multiple, `percentile_5y` is where today sits in that 5-year distribution (2 means lower than 98% of the last five years), and `position` buckets the percentile into one of five readings:

| position       | percentile\_5y | reading                   |
| -------------- | -------------- | ------------------------- |
| `deep_value`   | ≤ 20           | far below its own history |
| `below_median` | 20–45          | below its own history     |
| `at_median`    | 45–55          | near its own history      |
| `above_median` | 55–80          | above its own history     |
| `premium`      | ≥ 80           | far above its own history |

`coverage_pct` is how much of the 5-year window had data — read a high number (here 97) as a trustworthy context, a low one as thin. When there isn't enough history, `context` is `{ "available": false, "reason": ... }` instead, and a multiple without context is weaker evidence; say so rather than pretending the bare number is a verdict.

The top-level `valuation_context` block names which multiple to anchor on (`anchor`), why (`rationale`, e.g. `positive_earnings_period`), and repeats that multiple's reading. Use it as the headline; use the per-multiple `context` for the supporting detail.

## Worked example: is NVDA expensive? [#worked-example-is-nvda-expensive]

One snapshot call, one valuation call. The valuation response for NVDA (anchor block plus the P/E multiple shown; the live response also returns `ps_ttm`, `pb`, `ev_ebitda_ttm`, `ev_ebit_ttm`, `ev_sales_ttm`, `peg_1y`, a `yields` block, and `returns_on_capital`):

```json title="GET /v2/valuation?symbol=NVDA — trimmed"
{
  "data": {
    "symbol": "NVDA",
    "as_of": "2026-06-05T14:19:09Z",
    "freshness": "intraday",
    "market_status": "open",
    "market_cap_usd": 5313438000000,
    "multiples": {
      "pe_ttm": {
        "value": 33.29,
        "context": {
          "available": true,
          "median_5y": 57.67,
          "percentile_5y": 2.0,
          "position": "deep_value",
          "coverage_pct": 97
        }
      }
    },
    "valuation_context": {
      "anchor": "pe_ttm",
      "rationale": "positive_earnings_period",
      "value": 33.29,
      "median_5y": 57.67,
      "percentile_5y": 2.0,
      "position": "deep_value",
      "coverage_pct": 97
    }
  }
}
```

The MCP equivalent is `noxstock_valuation({ "symbol": "NVDA" })` and returns the identical envelope.

The reading writes itself, and it's a genuinely interesting one — a megacap trading near a 5-year low on its own earnings multiple:

> **NVDA looks cheap against its own history.** P/E (the anchor) is 33.29 versus a 5-year median of 57.67, sitting at the 2nd percentile of the last five years — a `deep_value` reading, with 97% history coverage. The picture is consistent across the EV multiples (EV/EBITDA and EV/EBIT also read `deep_value`), so this isn't one noisy ratio.
> Freshness: intraday, as\_of 2026-06-05T14:19:09Z, market open.

Note what that answer does *not* say: it doesn't call NVDA undervalued or a buy. "Cheap versus its own 5-year P/E" is a description of returned data. A recommendation is not.

## Non-payers: the dividend field is absent, not zero [#non-payers-the-dividend-field-is-absent-not-zero]

A multiple or yield that doesn't apply comes back as an unavailable envelope, never a fabricated 0. TSLA pays no dividend, so its `yields` block reports:

```json title="GET /v2/valuation?symbol=TSLA — yields, trimmed"
"yields": {
  "fcf_yield_pct": 0.45,
  "earnings_yield_pct": 0.25,
  "dividend_yield_pct": {
    "available": false,
    "reason": "no_dividend_payer"
  },
  "buyback_yield_pct_ttm": 0.0,
  "total_payout_yield_pct_ttm": 0.0
}
```

Read `available: false` as "noxstock has no dividend yield because the company doesn't pay one," and write that. Reporting a 0% yield would imply a paying stock that yields nothing, which is a different and wrong claim. (TSLA's multiples, by contrast, all read `premium` — the opposite of NVDA — so the same two-call check produces opposite, equally defensible answers.)

## ETFs: valuation is unsupported [#etfs-valuation-is-unsupported]

ETFs have no earnings, so equity multiples don't exist for them. `/v2/valuation?symbol=SPY` returns HTTP 200 with `freshness: "unsupported"`, `asset_type: "etf"`, and `reason: "etf_no_valuation_multiples"` — not an error to retry. Say multiples aren't available for that asset type and move on; the [freshness reference](/docs/reference/freshness) covers the `unsupported` state and how to branch on it.

<Card title="Compare basket" icon="columns-3" href="/docs/guides/compare-basket">
  Screen 2–4 names first, then run this check on the finalists only.
</Card>


# Hosted MCP quickstart (/docs/mcp/hosted)



Connect a client to `https://api.noxstock.com/mcp` and the 17 read-only `noxstock_*` tools load. Auth is the same `X-API-Key` header REST uses. This page gets you from zero to a verified `noxstock_snapshot` call.

<Warning>
  Keep the key in your client config, shell env, or a secret manager. Do not paste a full key into chat, logs, screenshots, or committed config.
</Warning>

<Steps>
  <Step>
    ## Get a key [#get-a-key]

    Create one at [noxstock.com/dashboard/keys](https://noxstock.com/dashboard/keys). The raw secret (prefix `nxs_`) is shown once at creation. Export it so the client config below can reference it:

    ```bash
    export NOXSTOCK_API_KEY="nxs_your_key_here"
    ```
  </Step>

  <Step>
    ## Add the server [#add-the-server]

    In Claude Code, register the hosted server over HTTP:

    ```bash
    claude mcp add --transport http noxstock https://api.noxstock.com/mcp \
      --header "X-API-Key: $NOXSTOCK_API_KEY"
    ```

    For a client that reads JSON config — Cursor, for example — add the server to its MCP config:

    ```json title="mcp.json"
    {
      "mcpServers": {
        "noxstock": {
          "url": "https://api.noxstock.com/mcp",
          "headers": {
            "X-API-Key": "nxs_your_key_here"
          }
        }
      }
    }
    ```
  </Step>

  <Step>
    ## Smoke test [#smoke-test]

    Confirm the tools loaded, then call `noxstock_snapshot` for AAPL:

    ```json
    {
      "tool": "noxstock_snapshot",
      "arguments": { "symbol": "AAPL" }
    }
    ```

    You get the REST `{ "data": ... }` envelope unchanged — as text JSON, structured content, or both, depending on the client:

    ```json title="noxstock_snapshot AAPL (trimmed)"
    {
      "data": {
        "symbol": "AAPL",
        "name": "Apple Inc",
        "currency": "USD",
        "as_of": "2026-06-05T14:19:06Z",
        "freshness": "intraday",
        "market_status": "open",
        "cache_age_seconds": 0,
        "quote": {
          "price": 314.86,
          "change_pct": 1.17,
          "previous_close": 311.23,
          "volume": 235657
        },
        "asset_type": "stock",
        "sector": "Technology",
        "industry": "Consumer Electronics"
      }
    }
    ```

    Trimmed; the live response also returns `performance`, `range_52w`, and a `fundamentals_quick` block. See [snapshot](/docs/api-reference/endpoints/core-context/snapshot) for the full payload.
  </Step>

  <Step>
    ## What failure looks like [#what-failure-looks-like]

    A REST error comes back in the `{ "error": ... }` envelope, which most clients render as a tool-error string `[CODE] message (retryable: ...)`. Two you should expect:

    ```text
    [UNAUTHORIZED] Missing or invalid X-API-Key header. (retryable: false)
    [PLAN_UPGRADE_REQUIRED] This endpoint requires Starter or Builder. Free includes search, coverage, snapshot, and valuation. (retryable: false)
    ```

    `PLAN_UPGRADE_REQUIRED` is an access result, not an outage. The full set of codes lives in [error codes](/docs/reference/error-codes).
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

Two failure modes that look similar but have different causes:

* **No tools load at all.** The client never reached or never authenticated with the server. Check the URL is exactly `https://api.noxstock.com/mcp`, the transport is HTTP (not stdio), and the `X-API-Key` header is actually being sent. At the wire, a missing or invalid key is rejected during the handshake with a plain HTTP `401` carrying the REST error envelope — most clients surface that as "no tools" or a connection error, not as a tool failure.
* **Tools load but a call errors.** The connection and key work; the plan or arguments do not. Tool failures render as the bracket string — `[PLAN_UPGRADE_REQUIRED] This endpoint requires Starter or Builder. … (retryable: false)` means a Free key called a paid tool.

On Free, only `noxstock_search`, `noxstock_coverage`, `noxstock_snapshot`, and `noxstock_valuation` are available — see [plans and limits](/docs/reference/plans-and-limits) for what each plan includes.

## Custom clients [#custom-clients]

Writing your own client instead of using a turnkey one? The server speaks standard MCP over Streamable HTTP: POST JSON-RPC to `https://api.noxstock.com/mcp` with your `X-API-Key` header plus `Accept: application/json, text/event-stream`, run the usual `initialize` → `notifications/initialized` handshake, then `tools/list` and `tools/call`. Nothing here is noxstock-specific — any spec-compliant MCP client implementation works unchanged.

<Card title="Tools reference" icon="braces" href="/docs/mcp/tools">
  All 17 tools, their REST routes, and argument conventions.
</Card>


# Local stdio setup (/docs/mcp/local-stdio)



Use this only when you are developing noxstock itself or testing against a local REST server. For agent integrations, use [hosted MCP](/docs/mcp/hosted) at `https://api.noxstock.com/mcp` instead.

**Prerequisite:** clone the [noxstock repo](https://github.com/noxstock/noxstock) and install [uv](https://docs.astral.sh/uv/) on the machine running the MCP client. The commands below run from the repo root.

## Local client config [#local-client-config]

Point a stdio-capable client at the server module. This config talks to the production REST API but runs the MCP process locally:

```json
{
  "mcpServers": {
    "noxstock": {
      "command": "uv",
      "args": ["run", "python", "-m", "noxstock.mcp.server", "--stdio"],
      "env": {
        "NOXSTOCK_API_BASE_URL": "https://api.noxstock.com",
        "NOXSTOCK_API_KEY": "nxs_your_key_here"
      }
    }
  }
}
```

## Against a localhost REST server [#against-a-localhost-rest-server]

Swap the base URL to your local API when iterating on REST and MCP together:

```json
{
  "mcpServers": {
    "noxstock": {
      "command": "uv",
      "args": ["run", "python", "-m", "noxstock.mcp.server", "--stdio"],
      "env": {
        "NOXSTOCK_API_BASE_URL": "http://127.0.0.1:8000",
        "NOXSTOCK_API_KEY": "local-dev-key"
      }
    }
  }
}
```

## Local Streamable HTTP [#local-streamable-http]

To run the server over HTTP locally instead of stdio:

```bash
uv run python -m noxstock.mcp.server --streamable-http --host 127.0.0.1 --port 8001
```

It listens at `/mcp`. Smoke-test it with:

```bash
uv run python scripts/smoke_mcp.py --url http://127.0.0.1:8001/mcp
```


# MCP overview (/docs/mcp/overview)



noxstock exposes 17 read-only `noxstock_*` tools over MCP. Each one calls a REST route and returns the exact same envelope, so an agent gets typed market context — snapshots, valuation, filings, insider activity — without you writing an API client.

Point a client at the hosted server and the tools appear:

```bash
claude mcp add --transport http noxstock https://api.noxstock.com/mcp \
  --header "X-API-Key: $NOXSTOCK_API_KEY"
```

That is a teaser. The [hosted quickstart](/docs/mcp/hosted) covers keys, a second client config, the smoke test, and what failures look like.

When a client display and the wire disagree, REST and the [OpenAPI schema](/docs/api-reference/overview) are the contract of record. MCP tools return REST envelopes unchanged; they never reshape them.

<CardGroup cols="2">
  <Card title="Hosted setup" icon="plug" href="/docs/mcp/hosted">
    Get a key, add the server, run the smoke test. Start here.
  </Card>

  <Card title="Tools reference" icon="braces" href="/docs/mcp/tools">
    All 17 tools, their REST routes, plan access, and argument conventions.
  </Card>

  <Card title="Local stdio" icon="terminal" href="/docs/mcp/local-stdio">
    Run the server locally for development or localhost testing.
  </Card>

  <Card title="Prompts and resources" icon="book-open" href="/docs/mcp/prompts-and-resources">
    Built-in prompt templates and JSON reference resources.
  </Card>
</CardGroup>


# Prompts and resources (/docs/mcp/prompts-and-resources)



The server ships four read-only resources and four prompts alongside the [tools](/docs/mcp/tools).

## Resources [#resources]

Resources are small JSON reference documents an agent can read without spending a tool call or a plan quota.

| Resource                                | Returns                                                        |
| --------------------------------------- | -------------------------------------------------------------- |
| `noxstock://reference/error-codes`      | Error codes with their `retryable` flag and meaning.           |
| `noxstock://reference/sectors`          | GICS sector to SPDR sector-ETF map used for relative strength. |
| `noxstock://reference/openapi`          | The REST OpenAPI schema.                                       |
| `noxstock://coverage/supported-tickers` | Every supported stock and ETF ticker.                          |

From an MCP client, list what is available and read one by URI:

```json
{ "method": "resources/list" }
```

```json
{
  "method": "resources/read",
  "params": { "uri": "noxstock://reference/error-codes" }
}
```

<Note>
  A resource that depends on a cached prerequisite returns `PREREQUISITE_MISSING`. This is the only place that code appears — REST endpoints never return it.
</Note>

## Prompts [#prompts]

| Prompt                    | Purpose                                 |
| ------------------------- | --------------------------------------- |
| `decision_brief(symbol)`  | Single-symbol context brief.            |
| `earnings_risk(symbol)`   | Earnings setup and risk for one symbol. |
| `insider_scan(symbol)`    | Form 4 activity review for one symbol.  |
| `compare_basket(symbols)` | 2–4 symbol comparison.                  |

Prompts are client-side templates. They tell the agent which tools to call in what order; they do not run a server-side workflow. Invoke one the way your client invokes prompts:

```json
{
  "method": "prompts/get",
  "params": {
    "name": "decision_brief",
    "arguments": { "symbol": "AAPL" }
  }
}
```

The client gets back the template text and the agent calls the tools it names. For the worked-out version of each flow, see [agent recipes](/docs/agents/recipes).


# MCP tools (/docs/mcp/tools)



Each tool wraps one REST route and returns its envelope unchanged. The endpoint page for each route documents the full parameters and response — the columns below are the map.

| Tool                       | REST route                                   | Plan    | Docs                                                                       |
| -------------------------- | -------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `noxstock_search`          | `GET /v2/search`                             | Free    | [search](/docs/api-reference/endpoints/discovery/search)                   |
| `noxstock_coverage`        | `GET /v2/coverage`                           | Free    | [coverage](/docs/api-reference/endpoints/discovery/coverage)               |
| `noxstock_snapshot`        | `GET /v2/snapshot`                           | Free    | [snapshot](/docs/api-reference/endpoints/core-context/snapshot)            |
| `noxstock_valuation`       | `GET /v2/valuation`                          | Free    | [valuation](/docs/api-reference/endpoints/core-context/valuation)          |
| `noxstock_compare`         | `GET /v2/compare`                            | Starter | [compare](/docs/api-reference/endpoints/core-context/compare)              |
| `noxstock_profile`         | `GET /v2/profile`                            | Starter | [profile](/docs/api-reference/endpoints/company-context/profile)           |
| `noxstock_fundamentals`    | `GET /v2/fundamentals`                       | Starter | [fundamentals](/docs/api-reference/endpoints/financials/fundamentals)      |
| `noxstock_earnings`        | `GET /v2/earnings`                           | Starter | [earnings](/docs/api-reference/endpoints/financials/earnings)              |
| `noxstock_dividends`       | `GET /v2/dividends`                          | Starter | [dividends](/docs/api-reference/endpoints/financials/dividends)            |
| `noxstock_technicals`      | `GET /v2/technicals`                         | Starter | [technicals](/docs/api-reference/endpoints/market-context/technicals)      |
| `noxstock_price_action`    | `GET /v2/price-action`                       | Starter | [price-action](/docs/api-reference/endpoints/market-context/price-action)  |
| `noxstock_history`         | `GET /v2/history`                            | Starter | [history](/docs/api-reference/endpoints/market-context/history)            |
| `noxstock_calendar`        | `GET /v2/calendar`                           | Starter | [calendar](/docs/api-reference/endpoints/events/calendar)                  |
| `noxstock_filings_list`    | `GET /v2/filings`                            | Starter | [filings list](/docs/api-reference/endpoints/sec-filings/filings-list)     |
| `noxstock_filings_get`     | `GET /v2/filings/{accession}`                | Starter | [filing](/docs/api-reference/endpoints/sec-filings/filing)                 |
| `noxstock_filings_section` | `GET /v2/filings/{accession}/section/{name}` | Starter | [filing section](/docs/api-reference/endpoints/sec-filings/filing-section) |
| `noxstock_insider`         | `GET /v2/insider`                            | Starter | [insider](/docs/api-reference/endpoints/sec-filings/insider)               |

Starter tools are also available on Builder. For per-plan rate limits and quotas, see [plans and limits](/docs/reference/plans-and-limits).

## Argument conventions [#argument-conventions]

Tool arguments are native JSON, not query strings. Three rules cover everything:

* **Lists are arrays.** `symbols` for compare is `["AAPL", "NVDA"]`; `forms` for filings is `["10-K", "10-Q"]`; `series` for history is a list. Do not pass comma-separated strings.
* **The history window argument is named `period`.** It maps to the REST `range` parameter (whose own legacy alias is also `period`), so values like `1y`, `5y`, `ytd`, and `max` apply. History also takes `cadence` (`daily`, `weekly`, `quarterly`, `annual`, `per-payment`) — and `series: ["dividend"]` requires `cadence: "per-payment"` explicitly.
* **Everything else mirrors the REST query params** with the same names and bounds: REST symbols match `^[A-Z0-9-]{1,8}$` after normalization — the tool schemas are more permissive (`^[A-Za-z0-9.-]{1,8}$`) and lowercase or dot forms like `brk.b` normalize server-side. `limit` is 1–100 for filings and 1–200 for insider, section `name` is one of `business`, `risk_factors`, `mda`, `quantitative_qualitative_disclosures`, `controls_and_procedures`, `press_release`.

The linked endpoint page is the full reference for each tool's parameters and response fields.


# Authentication (/docs/reference/authentication)



Send your key on every REST request in the `X-API-Key` header.

```bash
curl "https://api.noxstock.com/v2/snapshot?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

Use exactly that header name. There is no `Authorization: Bearer` path for REST, and the hosted MCP server authenticates with the same `X-API-Key` header.

## Keys [#keys]

Keys start with the `nxs_` prefix. Create and revoke them at [the dashboard](https://noxstock.com/dashboard/keys).

* The raw secret is shown **once**, at creation. Copy it before you close the dialog. noxstock cannot show it again.
* Keys do not expire on their own. They stay valid until you revoke them.
* Revocation takes effect within about a minute. After that, the key returns `UNAUTHORIZED`.

<Warning>
  Keep keys server-side. Do not ship them in browser bundles, mobile binaries without a backend broker, public repos, logs, screenshots, support threads, or model prompts. A leaked `nxs_` secret can call your whole quota until you revoke it.
</Warning>

## When a key fails [#when-a-key-fails]

A missing, malformed, or revoked key returns HTTP `401` with `UNAUTHORIZED`:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid X-API-Key header.",
    "retryable": false
  }
}
```

This is not retryable. Retrying with the same key wastes requests against your [rate limit](/docs/reference/plans-and-limits). Fix the header, swap in a live key, or create a new one. For the full status-and-retry table, see [error codes](/docs/reference/error-codes).


# Changelog (/docs/reference/changelog)



## 2026-06-05 — v2 reference rebuilt [#2026-06-05--v2-reference-rebuilt]

* Every response example in these docs is now a captured production payload, not a hand-written sample.
* Every response field is documented.
* The error envelope schema is published — see [response model](/docs/reference/response-model) and [error codes](/docs/reference/error-codes).
* Request and response samples ship in both Python and TypeScript.

## How we ship changes [#how-we-ship-changes]

**Additive changes** — new response fields, new endpoints — arrive without notice and without a version bump. Parse defensively: ignore fields you do not recognize and never fail on an unexpected key. A client that tolerates unknown fields keeps working as the API grows.

**Breaking changes** — removing or renaming a field, changing a type, narrowing behavior — get a dated entry here and advance the version. If it is not written on this page, it did not break.


# Coverage and known gaps (/docs/reference/coverage-and-gaps)



noxstock covers **5,119 symbols** — **5,062 stocks plus 57 ETFs**, all NYSE and NASDAQ listings (verified 2026-06-05). It is a supported-symbol API, not a market-wide dump: a symbol either resolves to data or it does not. Call `/v2/search` to discover symbols and `/v2/coverage` to confirm what a symbol supports before you build a workflow on it.

## The universe [#the-universe]

There are twelve data families: snapshot, profile, fundamentals, valuation, earnings, dividends, technicals, price action, history, calendar, filings, and insider.

* **4,136 US-domestic filers** support all twelve families. Every stock resolves to an SEC filer.
* **926 foreign private issuers (\~18%)** file 20-F / 40-F / 6-K instead of US-domestic forms. `/v2/filings` and `/v2/insider` return `unsupported` for them with reason `symbol_does_not_file_us_domestic_forms`; every other family works.
* **57 ETFs** carry market and dividend data but no issuer-level financials. Their non-applicable families return `unsupported` with reasons like `not_applicable_for_etf`.

Daily price history reaches back up to five years.

## What `/v2/coverage` returns [#what-v2coverage-returns]

Coverage is a per-symbol support map. For a US-domestic stock, everything is supported:

```json title="GET /v2/coverage?symbol=AAPL"
{
  "data": {
    "symbol": "AAPL",
    "asset_type": "stock",
    "cache_age_seconds": 0,
    "support": {
      "snapshot": { "supported": true },
      "profile": { "supported": true },
      "fundamentals": { "supported": true },
      "valuation": { "supported": true },
      "earnings": { "supported": true },
      "dividends": { "supported": true },
      "technicals": { "supported": true },
      "price_action": { "supported": true },
      "history": { "supported": true },
      "calendar": { "supported": true },
      "filings": { "supported": true },
      "insider": { "supported": true }
    }
  }
}
```

For an ETF, the issuer-level families come back unsupported with a machine-readable `reason` you can branch on:

```json title="GET /v2/coverage?symbol=SPY"
{
  "data": {
    "symbol": "SPY",
    "asset_type": "etf",
    "cache_age_seconds": 0,
    "support": {
      "snapshot": { "supported": true },
      "profile": { "supported": true },
      "fundamentals": { "supported": false, "reason": "etf_no_standalone_financial_statements" },
      "valuation": { "supported": false, "reason": "etf_no_valuation_multiples" },
      "earnings": { "supported": false, "reason": "etf_no_earnings_reports" },
      "dividends": { "supported": true },
      "technicals": { "supported": true },
      "price_action": { "supported": true },
      "history": { "supported": true },
      "calendar": { "supported": true },
      "filings": { "supported": false, "reason": "not_applicable_for_etf" },
      "insider": { "supported": false, "reason": "etf_no_insider_transactions" }
    }
  }
}
```

Branch on `support[family].supported` rather than guessing from `asset_type`. A foreign-issuer stock looks like AAPL above except `filings` and `insider` carry `supported: false` with reason `symbol_does_not_file_us_domestic_forms`.

## What noxstock does not cover [#what-noxstock-does-not-cover]

Market context for supported equities — not a trading or market-intelligence platform. None of these exist in v2, so do not imply them in UI copy, examples, or generated summaries:

* options data
* L2 / order-book depth
* global equities (US listings only)
* analyst consensus and price targets
* earnings-call transcripts
* news
* ownership / 13F filings
* order execution

Market data comes from licensed market-data sources; filings, filing sections, and insider activity come from SEC EDGAR. Provider names are not embedded in payloads.

## Cold EDGAR latency [#cold-edgar-latency]

The first read of a given filing pulls from EDGAR and can take up to \~20 seconds for a large 10-K; repeat reads return from cache in well under a second. Listing filings is fast either way — the cold cost is per accession, when metadata and sections are first fetched. Subsequent calls for that company are served from cache and return fast.

Design for the cold hit: use a loading state or a background job for SEC-heavy work, control concurrency when you fan out across many filers, and cache successful responses. Retry only retryable errors — never retry an `unsupported` filings or insider result, because the answer will not change. See [error codes](/docs/reference/error-codes) for which statuses retry.


# Error codes (/docs/reference/error-codes)



Failures use one envelope. Retry only when `error.retryable` is `true`.

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow request rate and retry.",
    "retryable": true
  }
}
```

`code` is the stable identifier to branch on; `message` is human-readable and may change. The table below carries the live messages captured against production.

| Code                        | HTTP | Retryable | What to do                                                                                                                                                                                                                                                 |
| --------------------------- | ---: | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`              |  401 | No        | Send a valid key in the `X-API-Key` header. Message: "Missing or invalid X-API-Key header." A revoked key lands here within about a minute of revocation. Do not retry the same key.                                                                       |
| `PLAN_UPGRADE_REQUIRED`     |  403 | No        | The route is gated above the key's plan. Message: "This endpoint requires Starter or Builder. Free includes search, coverage, snapshot, and valuation." Upgrade or stay on the four Free routes. See [plans and limits](/docs/reference/plans-and-limits). |
| `SYMBOL_INVALID`            |  400 | No        | The symbol failed grammar. Message: "Symbol must match `^[A-Z0-9-]{1,8}$` with dash-suffix share classes like BRK-B." Normalize before sending (`BRK.B` -> `BRK-B`).                                                                                       |
| `SYMBOL_UNKNOWN`            |  404 | No        | Well-formed symbol, not in the universe. Message: "Symbol 'ZZZQ' is not in the supported universe. Use /v2/search to discover supported tickers." Resolve it via `/v2/search` or `/v2/coverage`.                                                           |
| `PARAM_INVALID`             |  400 | No        | A query parameter is missing, duplicated, unknown, or out of range. Message: "Invalid request parameters." — &#x2A;*generic; it does not name the bad parameter.** Check the endpoint's param contract yourself.                                           |
| `RATE_LIMITED`              |  429 | Yes       | Per-minute, daily, or monthly limit hit. Honor `Retry-After` (seconds), lower concurrency, and cache repeat reads. Limits are in [plans and limits](/docs/reference/plans-and-limits).                                                                     |
| `UPSTREAM_UNAVAILABLE`      |  503 | Yes       | A market-data or SEC-backed source is briefly unavailable with no usable cache. Retry with backoff; keep first-hit SEC paths tolerant of latency.                                                                                                          |
| `AUTH_UPSTREAM_UNAVAILABLE` |  503 | Yes       | Key verification upstream is briefly unavailable. Retry shortly; the response sends `Retry-After: 5`.                                                                                                                                                      |
| `PREREQUISITE_MISSING`      |  409 | No        | **MCP resources only — never a REST endpoint.** A resource was read before the tool call that populates it. Run the prerequisite tool first, then read the resource.                                                                                       |

The plan gate runs before parameter validation: on a Free key, a bad parameter on a paid route returns `403 PLAN_UPGRADE_REQUIRED`, not `400`. And because `PARAM_INVALID` will not tell you which parameter is wrong, the per-endpoint pages are the authority on allowed parameter names, ranges, and enum values (form lists, `range`/`cadence` values, the 2–4 symbol bound on `/v2/compare`, and so on).

## The 429, with headers [#the-429-with-headers]

Successful responses (and `429`s) carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; other error responses do not (Unix epoch seconds). A 429 adds `Retry-After` in seconds. This is a live rate-limit response from `/v2/snapshot`:

```http title="HTTP 429 — headers + body"
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1780669200
Retry-After: 21

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow request rate and retry.",
    "retryable": true
  }
}
```

`Retry-After: 21` is the live-captured wait; sleep at least that long before retrying. If `Retry-After` is absent on a retryable error, fall back to exponential backoff with jitter.

## A retry loop that honors Retry-After [#a-retry-loop-that-honors-retry-after]

Retry only when `retryable` is `true`, prefer the server's `Retry-After`, and cap attempts so a sustained outage does not spin forever.

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="retry.py"
    import time
    import httpx

    RETRYABLE = {"RATE_LIMITED", "UPSTREAM_UNAVAILABLE", "AUTH_UPSTREAM_UNAVAILABLE"}


    def get(client: httpx.Client, path: str, params: dict, max_attempts: int = 4) -> dict:
        for attempt in range(max_attempts):
            r = client.get(path, params=params)
            body = r.json()
            if "data" in body:
                return body["data"]

            err = body["error"]
            last = attempt == max_attempts - 1
            if err["code"] not in RETRYABLE or last:
                raise RuntimeError(f"[{err['code']}] {err['message']}")

            retry_after = r.headers.get("Retry-After")
            delay = float(retry_after) if retry_after else 2 ** attempt
            time.sleep(delay)

        raise RuntimeError("exhausted retries")
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="retry.ts"
    const RETRYABLE = new Set([
      "RATE_LIMITED",
      "UPSTREAM_UNAVAILABLE",
      "AUTH_UPSTREAM_UNAVAILABLE",
    ]);

    const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

    export async function get<T>(
      url: string,
      init: RequestInit,
      maxAttempts = 4,
    ): Promise<T> {
      for (let attempt = 0; attempt < maxAttempts; attempt++) {
        const res = await fetch(url, init);
        const body = await res.json();
        if ("data" in body) return body.data as T;

        const { code, message } = body.error;
        const last = attempt === maxAttempts - 1;
        if (!RETRYABLE.has(code) || last) throw new Error(`[${code}] ${message}`);

        const retryAfter = res.headers.get("Retry-After");
        const delayMs = retryAfter ? Number(retryAfter) * 1000 : 2 ** attempt * 1000;
        await sleep(delayMs);
      }
      throw new Error("exhausted retries");
    }
    ```
  </Tab>
</Tabs>

## MCP surfaces the same errors [#mcp-surfaces-the-same-errors]

The MCP tools call the same REST endpoints and fail with the same `code`, `message`, and `retryable`. A tool error renders as a single string:

```text
[RATE_LIMITED] Rate limit exceeded. Please slow request rate and retry. (retryable: true)
```

Use the REST envelope and the OpenAPI spec as the contract of record for status codes and shapes.


# Freshness (/docs/reference/freshness)



Read `freshness` before you display, cache, or summarize a result. It tells you how current the data is and whether the endpoint even applies to this symbol. The five values are a closed set.

| Value         | Meaning                                                                            | What an agent does                                                                                     |
| ------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `intraday`    | A live intraday quote or market-context figure is included.                        | Use it for current context. Do not present it as exchange-grade real-time or as an execution price.    |
| `end_of_day`  | Last complete end-of-day close, statement, filing, dividend, or historical series. | Use it as the current value for fundamentals, filings, history, and after-hours market context.        |
| `stale`       | A cached fallback older than the normal window was served.                         | Show it with a "as of `as_of`" caveat; re-request if you need fresher.                                 |
| `degraded`    | A partial response — one source path was slow, limited, or unavailable.            | Use what is present, keep `null`s and reasons, and avoid conclusions that depend on the missing block. |
| `unsupported` | The endpoint does not apply to this symbol or asset type.                          | Show `reason`; do not re-request the same endpoint for the same symbol.                                |

## `as_of` [#as_of]

`as_of` is the timestamp the payload represents, in UTC ISO-8601 (`2026-06-05T14:19:06Z`).

* When the source supplies a timestamp, `as_of` is that upstream timestamp.
* When it does not, `as_of` is the moment noxstock generated the response.

Put `as_of` in any answer or label that asserts a current value, and do not silently swap it for local time:

```text
AAPL snapshot as of 2026-06-05T14:19:06Z, freshness: intraday.
```

## `market_status` [#market_status]

`market_status` is `"open"` or `"closed"`, computed from request time against the regular NYSE/NASDAQ session: 09:30–16:00 ET, **Monday through Friday, excluding US market holidays** (about ten per year — New Year's Day, MLK Day, Presidents' Day, Good Friday, Memorial Day, Juneteenth, Independence Day, Labor Day, Thanksgiving, Christmas). A weekday holiday reads `"closed"` even during what would be session hours.

It is a session hint, not an exchange operations feed. Do not read halts, auction state, venue status, or execution readiness into it. The stateless lookup routes `/v2/search` and `/v2/coverage` omit it entirely.

## Detecting staleness yourself [#detecting-staleness-yourself]

`freshness` is the headline; `as_of` and `cache_age_seconds` are the precise instruments. `cache_age_seconds` is how many seconds the served payload has been cached — `0` means it was computed on this request, and a large value means a cached read ([response model](/docs/reference/response-model) owns this field).

To decide whether a number is current enough for your product, compare against `as_of` and `cache_age_seconds` rather than guessing from `freshness` alone:

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="staleness.py"
    from datetime import datetime, timezone

    def is_stale(data: dict, max_age_seconds: int) -> bool:
        # Cache age is the direct signal: how long this payload has been held.
        if data.get("cache_age_seconds", 0) > max_age_seconds:
            return True
        # as_of guards against an old upstream timestamp behind a fresh cache.
        as_of = datetime.fromisoformat(data["as_of"].replace("Z", "+00:00"))
        age = (datetime.now(timezone.utc) - as_of).total_seconds()
        return age > max_age_seconds
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="staleness.ts"
    function isStale(data: {
      as_of: string;
      cache_age_seconds?: number;
    }, maxAgeSeconds: number): boolean {
      if ((data.cache_age_seconds ?? 0) > maxAgeSeconds) return true;
      const ageSeconds = (Date.now() - Date.parse(data.as_of)) / 1000;
      return ageSeconds > maxAgeSeconds;
    }
    ```
  </Tab>
</Tabs>

Pick `max_age_seconds` by data family: seconds-to-minutes for an intraday quote, hours for fundamentals (a real `/v2/fundamentals` read returned `cache_age_seconds: 16096`, about four and a half hours, which is normal — statements do not move intraday).

## Unsupported is a 200, not an error [#unsupported-is-a-200-not-an-error]

When an endpoint does not apply, you get HTTP 200 with `freshness: "unsupported"` and a machine-readable `reason`. This is a live `/v2/valuation` for SPY:

```json title="GET /v2/valuation?symbol=SPY — HTTP 200"
{
  "data": {
    "symbol": "SPY",
    "asset_type": "etf",
    "freshness": "unsupported",
    "reason": "etf_no_valuation_multiples",
    "as_of": "2026-06-05T14:19:10Z",
    "market_status": "open",
    "cache_age_seconds": 0
  }
}
```

The reasons are stable strings you can branch on — `etf_no_valuation_multiples`, `symbol_does_not_file_us_domestic_forms`, `not_applicable_for_etf`. Retrying will not change the answer; which families return `unsupported` for which assets is documented in [coverage and gaps](/docs/reference/coverage-and-gaps).

## When to re-request [#when-to-re-request]

`freshness` controls retry behavior for successful responses; `error.retryable` controls it for failures.

* `stale` — re-request only if your product needs fresher data right now.
* `degraded` — re-request only when the missing block is the one you need.
* `unsupported` — do not re-request without changing the endpoint or the symbol.
* For `RATE_LIMITED`, `UPSTREAM_UNAVAILABLE`, and `AUTH_UPSTREAM_UNAVAILABLE`, follow `error.retryable` and `Retry-After` per the [error codes](/docs/reference/error-codes).


# Plans and limits (/docs/reference/plans-and-limits)



A plan sets three things for a key: which routes it can call, how many requests per minute it gets, and its quota over a longer window. The data on every route is identical across plans — paid plans buy throughput, not different numbers.

| Plan    | Per minute |        Quota | Routes                                        |
| ------- | ---------: | -----------: | --------------------------------------------- |
| Free    |     30/min |      100/day | `search`, `coverage`, `snapshot`, `valuation` |
| Starter |     60/min | 10,000/month | all routes                                    |
| Builder |    300/min | 75,000/month | all routes                                    |

Prices are at [/pricing](/pricing). Pick Builder over Starter when you need the higher ceilings — 300/min and 75,000/month against 60/min and 10,000 — for fan-out, batch jobs, or bursty agent traffic. The responses are byte-for-byte the same.

## Route access [#route-access]

Free covers the proof loop: discover a symbol with `/v2/search`, confirm what it supports with `/v2/coverage`, pull a `/v2/snapshot`, and run a `/v2/valuation`. Every other route requires Starter or Builder.

A Free key that calls a paid route gets HTTP `403` with `PLAN_UPGRADE_REQUIRED`:

```json
{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "This endpoint requires Starter or Builder. Free includes search, coverage, snapshot, and valuation.",
    "retryable": false
  }
}
```

This is not retryable. Upgrade the key, or call one of the four Free routes.

## Rate-limit headers [#rate-limit-headers]

Successful responses carry three headers describing your current minute bucket (4xx errors other than `429` do not include them — track your budget from successes):

```text
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1798912312
```

| Header                  | Meaning                                        |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Requests allowed in the current minute window. |
| `X-RateLimit-Remaining` | Requests left in that window.                  |
| `X-RateLimit-Reset`     | Unix epoch seconds when the window resets.     |

Read `X-RateLimit-Remaining` to pace yourself before you ever hit a `429`.

## Hitting a ceiling [#hitting-a-ceiling]

When you exceed the per-minute rate or exhaust your quota, requests return HTTP `429` with `RATE_LIMITED` until the window resets — the **daily** window for Free, the **monthly** window for Starter and Builder. A `429` adds a `Retry-After` header (seconds) and sets `X-RateLimit-Remaining` to `0`.

The headers on a `429` describe **whichever window tripped**. A minute-bucket 429 shows your per-minute limit and a `Retry-After` of seconds. A quota 429 flips `X-RateLimit-Limit` to the quota itself (100 on Free), sets `X-RateLimit-Reset` to the window's end, and sends a `Retry-After` of hours — a Free daily 429 reports the seconds until midnight UTC. There is no header that counts the daily or monthly budget down during normal operation; if quota matters to your job, count requests yourself.

This is a minute-bucket 429:

```http title="429 captured 2026-06-05"
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1780669200
Retry-After: 21

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow request rate and retry.",
    "retryable": true
  }
}
```

`RATE_LIMITED` is retryable. Stop sending for that key, wait `Retry-After` (21 seconds in this capture) or until `X-RateLimit-Reset`, then resume at lower concurrency and cache repeat reads. The same gating applies to the hosted MCP tools, since they call the same routes. For retry mechanics across every error, see [error codes](/docs/reference/error-codes).


# Response model (/docs/reference/response-model)



Every noxstock REST response is one of two top-level shapes. Branch on which key is present, not on the endpoint and not on the HTTP status.

| Outcome | Top-level shape                                   |
| ------- | ------------------------------------------------- |
| Success | `{ "data": ... }`                                 |
| Failure | `{ "error": { "code", "message", "retryable" } }` |

There is never a raw endpoint object, a bare array, or an upstream provider payload at the top level. The MCP tools return the identical envelope, so a parser written against this page works for both surfaces.

## Success envelope [#success-envelope]

Success is exactly a top-level `data` object. Here is a real `/v2/snapshot` response for AAPL, trimmed to the wrapper and the common fields — the live response also carries `quote`, `performance`, `range_52w`, and `fundamentals_quick` blocks.

```json title="GET /v2/snapshot?symbol=AAPL"
{
  "data": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "as_of": "2026-06-05T14:19:06Z",
    "freshness": "intraday",
    "market_status": "open",
    "cache_age_seconds": 0,
    "asset_type": "stock"
  }
}
```

The object inside `data` is endpoint-specific. The wrapper is not.

## Error envelope [#error-envelope]

Failure is exactly a top-level `error` object with three fields. This is a live 429 from `/v2/snapshot`:

```json title="GET /v2/snapshot?symbol=AAPL — HTTP 429"
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please slow request rate and retry.",
    "retryable": true
  }
}
```

`error.retryable` is the retry contract. Retry only when it is `true`, and still back off — see [error codes](/docs/reference/error-codes) for the full table and the worked retry loop. On a 429 the response also carries rate-limit headers; this example sent `Retry-After: 21` and `X-RateLimit-Remaining: 0`.

## Common fields on `data` [#common-fields-on-data]

Most symbol endpoints put these fields at the top of `data`. The exact set varies by endpoint, but when a field appears it means the same thing everywhere.

| Field               | Meaning                                                                                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `symbol`            | The resolved symbol for endpoints that take one (normalized, e.g. `BRK-B`).                                                                                               |
| `as_of`             | The timestamp the payload represents — upstream timestamp when the source gives one, otherwise generation time. UTC ISO-8601. See [freshness](/docs/reference/freshness). |
| `freshness`         | One of `intraday`, `end_of_day`, `stale`, `degraded`, `unsupported`. Owned by [freshness](/docs/reference/freshness).                                                     |
| `market_status`     | `open` or `closed`. Omitted on stateless lookup routes (`/v2/search`, `/v2/coverage`). Owned by [freshness](/docs/reference/freshness).                                   |
| `cache_age_seconds` | Seconds the served data has been cached. `0` means freshly computed; a large value means a cached read. Pair it with `as_of` to judge staleness.                          |
| `currency`          | Present only when the payload carries monetary values; `USD` across the supported universe.                                                                               |
| `asset_type`        | `stock` or `etf`. Present where the two shapes branch.                                                                                                                    |
| `period`            | Present on period-based endpoints (`/v2/fundamentals`, `/v2/history`). Units owned by [units and fields](/docs/reference/units-and-fields).                               |

`cache_age_seconds` is the field to read when you care whether a number is live. In the snapshot above it is `0` (computed on request); a `/v2/fundamentals` read for the same symbol returned `16096`, meaning the statement model was served from a cache roughly four and a half hours old. That is expected for fundamentals — statements do not change intraday — but it is the value to surface if your product needs to reason about how current a figure is.

## Unsupported is a success, not an error [#unsupported-is-a-success-not-an-error]

When an endpoint does not apply to a symbol, you get HTTP 200 with a normal `data` object whose `freshness` is `"unsupported"` and whose `reason` is a machine-readable string. This is a live `/v2/valuation` for SPY — ETFs have no valuation multiples:

```json title="GET /v2/valuation?symbol=SPY — HTTP 200"
{
  "data": {
    "symbol": "SPY",
    "asset_type": "etf",
    "freshness": "unsupported",
    "reason": "etf_no_valuation_multiples",
    "as_of": "2026-06-05T14:19:10Z",
    "market_status": "open",
    "cache_age_seconds": 0
  }
}
```

Do not treat this as an outage and do not retry it for the same symbol — the answer will not change. Show the `reason` and move on. [Coverage and gaps](/docs/reference/coverage-and-gaps) lists which families return `unsupported` for which assets.

## Three ways a value can be absent [#three-ways-a-value-can-be-absent]

Inside a `data` object, a value can be missing in three distinct ways, and they mean different things. This is the table other pages link to; do not re-derive it elsewhere.

| Pattern              | What it looks like                                 | Meaning                                                                         | What to do                                                                    |
| -------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `null`               | `"field": null`                                    | The field is meaningful here, but no value is available for this row or symbol. | Render "not available" or omit the cell. Do not compute with it.              |
| Omitted key          | the key is simply not present                      | A persistent source gap, or an optional field that does not apply.              | Treat as absent. Do not invent it.                                            |
| Unavailable envelope | `"field": { "available": false, "reason": "..." }` | The value is intentionally suppressed, and `reason` says why.                   | Keep the `reason` if you display the field. Do not retry to "get the number." |

The unavailable envelope is common and load-bearing. It replaces a scalar in place — wherever a number would sit, you may instead find `{ "available": false, "reason": ... }`. A real example from `/v2/insider`, where a gift has no market price:

```json
{
  "transaction_kind": "gift",
  "shares": 65000,
  "price_per_share": { "available": false, "reason": "gift_no_market_price" },
  "value_usd": { "available": false, "reason": "gift_no_market_price" }
}
```

Parse defensively: before doing math on a field that is normally a number, check that it is one. Financial-statement guardrails use the same shape — for example `interest_coverage` becomes `{ "available": false, "reason": "zero_interest_expense" }` rather than dividing by zero.

## Parse by envelope, branching on retryable [#parse-by-envelope-branching-on-retryable]

A correct client reads `data` versus `error` first, and on error keeps `code` and `retryable` so the caller can decide whether to retry. The two parsers below do exactly that.

<Tabs items="[&#x22;Python&#x22;, &#x22;TypeScript&#x22;]">
  <Tab value="Python">
    ```python title="parse.py"
    import httpx


    class NoxstockError(Exception):
        def __init__(self, code: str, message: str, retryable: bool, status: int):
            super().__init__(f"[{code}] {message}")
            self.code = code
            self.message = message
            self.retryable = retryable
            self.status = status


    def parse(response: httpx.Response) -> dict:
        body = response.json()
        if "error" in body:
            err = body["error"]
            raise NoxstockError(
                err["code"], err["message"], err["retryable"], response.status_code
            )
        return body["data"]
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts title="parse.ts"
    type Envelope<T> =
      | { data: T }
      | { error: { code: string; message: string; retryable: boolean } };

    export class NoxstockError extends Error {
      constructor(
        readonly code: string,
        message: string,
        readonly retryable: boolean,
        readonly status: number,
      ) {
        super(`[${code}] ${message}`);
      }
    }

    export async function parse<T>(response: Response): Promise<T> {
      const body = (await response.json()) as Envelope<T>;
      if ("error" in body) {
        const { code, message, retryable } = body.error;
        throw new NoxstockError(code, message, retryable, response.status);
      }
      return body.data;
    }
    ```
  </Tab>
</Tabs>

The caller catches `NoxstockError` and checks `retryable` before deciding to retry. The full backoff loop that honors `Retry-After` lives with the [error codes](/docs/reference/error-codes).

<Card title="Error codes" icon="shield" href="/docs/reference/error-codes">
  Every code, its HTTP status, whether it is retryable, and what to do about it.
</Card>


# Units and fields (/docs/reference/units-and-fields)



Field names carry their units in the suffix, so the number itself is unambiguous once you know the suffix. Store and compute on the raw value; only convert at the display edge, and label the conversion when you do.

The same metric can differ by a rounding step across endpoints — snapshot and valuation may compute `dividend_yield_pct` from reads seconds apart, so `0.86` on one and `0.85` on the other is normal. Compare `as_of` timestamps before treating a cross-endpoint difference as a data problem.

## Unit suffixes [#unit-suffixes]

These are the suffixes you will see across the API, each verified against live fixtures.

| Suffix             | Meaning                                                 | Example from a live response                                                                           |
| ------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `_usd`             | Whole US dollars — not thousands, not millions.         | `market_cap_usd: 4569211202200` is $4.569T; `value_usd: 15551000.0` is $15.55M.                        |
| `_pct`             | Percentage points, already scaled — not a 0–1 fraction. | `dividend_yield_pct: 0.34` means 0.34%; `fcf_margin_pct: 24.04` means 24.04%.                          |
| `_seconds`         | A duration in seconds.                                  | `cache_age_seconds: 16096`.                                                                            |
| share-count fields | Whole share counts.                                     | `shares_outstanding: 14725873000`, plus `shares_basic`, `shares_diluted`, `common_shares_outstanding`. |
| no suffix          | A dimensionless ratio or multiple.                      | `current_ratio: 1.07`, `debt_to_equity: 0.8`, `pe_ttm: 37.28`, `beta_1y: 0.96`.                        |

A few bare fields are dollars by convention rather than suffix — line items inside a statement block (`revenue`, `operating_cash_flow`, `capex`) and `price_per_share`. The enclosing object carries `"currency": "USD"`; read it rather than assuming.

### The `_pct` rule, worked [#the-_pct-rule-worked]

`_pct` values are percentage points. To use one as a multiplier, divide by 100 first.

```python
yield_pct = 0.34          # from dividend_yield_pct
annual_income = price * (yield_pct / 100)   # NOT price * 0.34
```

Treating `dividend_yield_pct: 0.34` as the fraction `0.34` overstates the figure by 100x. This is the single most common unit mistake; the divide-by-100 is on you, not the API.

## Signs are meaningful — never flip them [#signs-are-meaningful--never-flip-them]

A negative number is information. Preserve the sign through your pipeline.

```json
{
  "drawdown_from_high_pct": -1.8,
  "working_capital_change": -14772000000,
  "net_value_usd": -111705105.08
}
```

`drawdown_from_high_pct: -1.8` says the price sits 1.8% below its 52-week high — the negative is the drawdown. A negative `working_capital_change` is a normal cash-flow movement, not an error. A negative `net_value_usd` on an insider rollup signals net selling. Stripping the minus sign to make a value "look clean" changes its meaning.

## Timestamps and dates [#timestamps-and-dates]

Point-in-time timestamps are UTC ISO-8601 with a `Z`:

```json
"as_of": "2026-06-05T14:19:06Z"
```

Date-only fields use `YYYY-MM-DD`:

```json
"period_end": "2026-03-28"
```

Keep the two kinds separate. `as_of` timestamps the payload and its source context ([freshness](/docs/reference/freshness) owns its semantics); `period_end`, `filing_date`, `transaction_date`, and event `date` are business or filing dates, not data-currency signals.

## The `/v2/history` columnar shape [#the-v2history-columnar-shape]

`/v2/history` returns a columnar table: a `columns` array naming each position, and `rows` as compact arrays in that exact order. Read `columns` first, then index `rows` by position — never assume a fixed layout, because the columns follow your `series` request.

Three fields tie a history response together:

* `period` — the lookback window you asked for (`1m`, `1y`, `5y`, …); the request parameter is `range`, and `period` echoes it back.
* `cadence` — the row spacing: `daily`, `weekly`, `quarterly`, `annual`, or `per-payment`.
* `columns` — the order of values inside every row.

This is a live `/v2/history?symbol=AAPL&series=close&range=1m`, trimmed to the first three of 22 daily rows (the live response returns the full month):

```json title="GET /v2/history?symbol=AAPL&series=close&range=1m"
{
  "data": {
    "symbol": "AAPL",
    "period": "1m",
    "cadence": "daily",
    "as_of": "2026-06-05T14:19:11Z",
    "freshness": "intraday",
    "columns": ["date", "close"],
    "rows": [
      ["2026-05-05", 283.9180829493],
      ["2026-05-06", 287.2450138249],
      ["2026-05-07", 287.175078341]
    ]
  }
}
```

`columns` is `["date", "close"]`, so `row[0]` is the date and `row[1]` is the close. Request more series and both `columns` and each row grow in lockstep — `series=close,volume,rsi_14` yields `["date", "close", "volume", "rsi_14"]` and four-element rows. History values are not pre-rounded; round at display time if you need to.

## Absent values [#absent-values]

A value can be `null`, an omitted key, or an `{ "available": false, "reason": ... }` envelope, and the three mean different things. That table is owned by the [response model](/docs/reference/response-model#three-ways-a-value-can-be-absent) — check there before writing absence-handling code, and do not invent a field that the response did not return.


# Get company or ETF profile (/docs/api-reference/endpoints/company-context/profile)

`GET https://api.noxstock.com/v2/profile`

Who the company is: description, sector and industry, exchange, headquarters, website, CIK, market cap, and shares outstanding. ETF profiles return fund facts (issuer, yield) instead; ETF holdings are not part of v2.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (AAPL)

```json
{
  "data": {
    "as_of": "2026-06-05T06:38:12Z",
    "asset_type": "stock",
    "cache_age_seconds": 27658,
    "cik": "0000320193",
    "country": "US",
    "currency": "USD",
    "description": "Business Company Background The Company designs, manufactures and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related services. The Company’s fiscal year is the 52- or 53-week period that ends on the last Saturday of September. Products iPhone iPhone® is the Company’s line of smartphones based on its iOS operating system. The iPhone line includes iPhone 17 Pro, iPhone Air™, iPhone 17, iPhone 16 and iPhone 16e. Mac Mac® is the Company’s",
    "dividend_yield_pct": 0.35,
    "exchange": "NASDAQ",
    "fiscal_year_end_month": 9,
    "freshness": "end_of_day",
    "headquarters": "Cupertino, CA",
    "industry": "Consumer Electronics",
    "market_cap_usd": 4569211202200,
    "market_status": "open",
    "name": "Apple Inc",
    "sector": "Technology",
    "shares_outstanding": 14725873000,
    "symbol": "AAPL",
    "website": "http://www.apple.com"
  }
}
```

### ETF (SPY)

```json
{
  "data": {
    "as_of": "2026-06-05T06:38:31Z",
    "asset_type": "etf",
    "cache_age_seconds": 27639,
    "currency": "USD",
    "description": "Historical ETF prices for SPDR S&P 500 ETF (SPY). SPDR S&P 500 ETF Trust (the Trust) is an exchange traded fund. The Trust corresponds to the price and yield performance of the S&P 500 Index. The S&P 500 Index is composed of 500 selected stocks and spans over 24 separate industry groups. The Fund's investment sectors include information technology, financials, energy, health care, consumer staples, industrials, consumer discretionary, materials, utilities and telecommunication services.",
    "dividend_yield_pct": 0.95,
    "exchange": "NYSE",
    "freshness": "end_of_day",
    "issuer": "SPDR S&P 500 ETF TRUST",
    "market_status": "open",
    "name": "SPDR S&P 500 ETF Trust",
    "shares_outstanding": {
      "available": false,
      "reason": "etf_shares_outstanding_unavailable_upstream"
    },
    "symbol": "SPY"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/profile?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/profile",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/profile?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Compare symbols (/docs/api-reference/endpoints/core-context/compare)

`GET https://api.noxstock.com/v2/compare`

A 2–4 symbol scorecard over selected snapshot and technicals fields. Fields a symbol cannot supply are listed per symbol in `fields_omitted_by_symbol` instead of appearing as null. More than 4 symbols is `PARAM_INVALID` — compare first, then deepen only finalists.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbols` | query | yes | Comma-separated list of 2-4 distinct ticker symbols. Each symbol is validated against the supported universe. |
| `fields` | query | no | Comma-separated subset of compare fields. Allowed values: price, pct_1d, pct_1m, pct_ytd, pct_1y, vs_spy_pct_1y, range_52w_position_pct, drawdown_from_high_pct, market_cap_usd, pe_ttm, ps_ttm, pb, peg_1y, ev_ebitda_ttm, fcf_yield_pct, dividend_yield_pct, beta_1y, rsi_14, rsi_zone, trending, golden_cross_active, vs_sma_200_pct, distance_from_52w_high_pct. Defaults when omitted: price, pct_1y, vs_spy_pct_1y, pe_ttm, rsi_14, trending. |

## Response examples (captured from production)

### Three-way (NVDA, AMD, INTC)

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:11Z",
    "cache_age_seconds": 0,
    "fields_omitted_by_symbol": {},
    "fields_requested": [
      "price",
      "pct_1y",
      "vs_spy_pct_1y",
      "pe_ttm",
      "rsi_14",
      "trending"
    ],
    "freshness": "intraday",
    "market_status": "open",
    "symbols": [
      {
        "pct_1y": 54.29,
        "pe_ttm": 33.29,
        "price": 212.66,
        "rsi_14": 54.43,
        "symbol": "NVDA",
        "trending": false,
        "vs_spy_pct_1y": 25.78
      },
      {
        "pct_1y": 341.22,
        "pe_ttm": 170.3,
        "price": 493.76,
        "rsi_14": 70.57,
        "symbol": "AMD",
        "trending": true,
        "vs_spy_pct_1y": 312.72
      },
      {
        "pct_1y": 452,
        "pe_ttm": -175.91,
        "price": 105.07,
        "rsi_14": 55.31,
        "symbol": "INTC",
        "trending": true,
        "vs_spy_pct_1y": 423.5
      }
    ]
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/compare?symbols=NVDA,AMD,INTC" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/compare",
    params={"symbols": "NVDA,AMD,INTC"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/compare?symbols=NVDA,AMD,INTC", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get decision snapshot (/docs/api-reference/endpoints/core-context/snapshot)

`GET https://api.noxstock.com/v2/snapshot`

One-call decision context: live quote, performance over seven windows plus relative-to-SPY, 52-week range position, and a `fundamentals_quick` block (market cap, P/E, FCF yield, and peers). The shape differs by asset type: ETF responses omit `market_cap_usd` and return `{available: false, reason}` objects for earnings-based ratios instead of numbers — handle both.

Access: all plans, including Free.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (AAPL)

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:06Z",
    "asset_type": "stock",
    "cache_age_seconds": 0,
    "currency": "USD",
    "freshness": "intraday",
    "fundamentals_quick": {
      "beta_1y": 0.96,
      "dividend_yield_pct": 0.34,
      "enterprise_value_usd": 4585415202200,
      "ev_ebitda_ttm": 28.61,
      "fcf_yield_pct": 2.83,
      "market_cap_usd": 4569211202200,
      "pb": 42.91,
      "pe_ttm": 37.28,
      "peg_1y": 1.66,
      "ps_ttm": 10.12,
      "shares_outstanding": 14725873000,
      "ttm_eps_diluted": 8.26,
      "ttm_net_income_usd": 122575000000,
      "ttm_revenue_usd": 451442000000
    },
    "industry": "Consumer Electronics",
    "market_status": "open",
    "name": "Apple Inc",
    "performance": {
      "pct_1d": 1.17,
      "pct_1m": 9.62,
      "pct_1y": 54.06,
      "pct_3m": 21,
      "pct_3y": 75.72,
      "pct_5d": -0.41,
      "pct_ytd": 15.06,
      "vs_sector_status": {
        "supported": true
      },
      "vs_spy_pct_1m": 5.02,
      "vs_spy_pct_1y": 25.56,
      "vs_spy_pct_ytd": 3.93
    },
    "quote": {
      "change_abs": 3.63,
      "change_pct": 1.17,
      "day_high": 315.19,
      "day_low": 312.42,
      "day_open": 313.26,
      "previous_close": 311.23,
      "price": 314.86,
      "volume": 235657
    },
    "range_52w": {
      "drawdown_from_high_pct": -1.8,
      "high": 316.94,
      "low": 194.3,
      "position_pct": 95.3
    },
    "sector": "Technology",
    "symbol": "AAPL"
  }
}
```

### ETF (SPY)

Note the `{available: false, reason}` envelopes inside `fundamentals_quick` and the absent `market_cap_usd`.

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:07Z",
    "asset_type": "etf",
    "benchmark_role": "market_proxy",
    "cache_age_seconds": 0,
    "currency": "USD",
    "etf_category": "broad_market",
    "etf_focus": "S&P 500 large-cap U.S. equity exposure",
    "freshness": "intraday",
    "fundamentals_quick": {
      "beta_1y": 1,
      "dividend_yield_pct": 0.96,
      "enterprise_value_usd": {
        "available": false,
        "reason": "etf_enterprise_value_not_applicable"
      },
      "ev_ebitda_ttm": {
        "available": false,
        "reason": "etf_no_ebitda"
      },
      "fcf_yield_pct": {
        "available": false,
        "reason": "etf_no_cash_flow_statements"
      },
      "pb": {
        "available": false,
        "reason": "etf_no_book_value"
      },
      "pe_ttm": {
        "available": false,
        "reason": "etf_no_earnings"
      },
      "peg_1y": {
        "available": false,
        "reason": "etf_no_earnings_growth"
      },
      "ps_ttm": {
        "available": false,
        "reason": "etf_no_revenue"
      },
      "shares_outstanding": {
        "available": false,
        "reason": "etf_shares_outstanding_unavailable_upstream"
      },
      "ttm_eps_diluted": {
        "available": false,
        "reason": "etf_no_eps"
      },
      "ttm_net_income_usd": {
        "available": false,
        "reason": "etf_no_net_income"
      },
      "ttm_revenue_usd": {
        "available": false,
        "reason": "etf_no_revenue"
      }
    },
    "market_status": "open",
    "name": "SPDR S&P 500 ETF Trust",
    "performance": {
      "pct_1d": -0.84,
      "pct_1m": 4.6,
      "pct_1y": 28.5,
      "pct_3m": 12.91,
      "pct_3y": 84.22,
      "pct_5d": 0.33,
      "pct_ytd": 11.13,
      "vs_sector_status": {
        "reason": "not_applicable_for_etf",
        "supported": false
      },
      "vs_spy_pct_1m": 0,
      "vs_spy_pct_1y": 0,
      "vs_spy_pct_ytd": 0
    },
    "quote": {
      "change_abs": -6.38,
      "change_pct": -0.84,
      "day_high": 753.15,
      "day_low": 748.01,
      "day_open": 751.73,
      "previous_close": 757.09,
      "price": 750.71,
      "volume": 185539
    },
    "range_52w": {
      "drawdown_from_high_pct": -0.44,
      "high": 760.4,
      "low": 584.35,
      "position_pct": 98.1
    },
    "sector": "Broad Market",
    "symbol": "SPY"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/snapshot?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/snapshot",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/snapshot?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get valuation context (/docs/api-reference/endpoints/core-context/valuation)

`GET https://api.noxstock.com/v2/valuation`

Seven multiples (P/E, P/S, P/B, EV/EBITDA, EV/EBIT, EV/Sales, PEG), each with 5-year context — median, percentile, and a `position` reading from `deep_value` to `premium` — plus five yields and returns on capital. Yields that do not apply return `{available: false, reason}` objects, never zero. ETFs return `freshness: "unsupported"`.

Access: all plans, including Free.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (NVDA)

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:09Z",
    "cache_age_seconds": 0,
    "currency": "USD",
    "enterprise_value_usd": 5245214000000,
    "freshness": "intraday",
    "market_cap_usd": 5313438000000,
    "market_status": "open",
    "multiples": {
      "ev_ebit_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 98,
          "median_5y": 53.63,
          "percentile_5y": 1,
          "position": "deep_value"
        },
        "value": 27.64
      },
      "ev_ebitda_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 98,
          "median_5y": 48.69,
          "percentile_5y": 2,
          "position": "deep_value"
        },
        "value": 27.18
      },
      "ev_sales_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 98,
          "median_5y": 24.94,
          "percentile_5y": 24,
          "position": "below_median"
        },
        "value": 20.69
      },
      "pb": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 34.4,
          "percentile_5y": 33,
          "position": "below_median"
        },
        "value": 27.18
      },
      "pe_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 97,
          "median_5y": 57.67,
          "percentile_5y": 2,
          "position": "deep_value"
        },
        "value": 33.29
      },
      "peg_1y": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 0.33,
          "percentile_5y": 41,
          "position": "below_median"
        },
        "value": 0.16
      },
      "ps_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 98,
          "median_5y": 25.21,
          "percentile_5y": 25,
          "position": "below_median"
        },
        "value": 20.96
      }
    },
    "returns_on_capital": {
      "flags": [],
      "roa_pct": 83.11,
      "roce_pct": 105.39,
      "roe_pct": 111.66,
      "roic_pct": 105.39
    },
    "symbol": "NVDA",
    "valuation_context": {
      "anchor": "pe_ttm",
      "coverage_pct": 97,
      "median_5y": 57.67,
      "percentile_5y": 2,
      "position": "deep_value",
      "rationale": "positive_earnings_period",
      "value": 33.29
    },
    "yields": {
      "buyback_yield_pct_ttm": 1,
      "dividend_yield_pct": 0.46,
      "earnings_yield_pct": 3,
      "fcf_yield_pct": 2.24,
      "total_payout_yield_pct_ttm": 1.02
    }
  }
}
```

### ETF (SPY) — unsupported

ETFs have no valuation multiples; the success envelope carries `freshness: "unsupported"` and a `reason`.

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:10Z",
    "asset_type": "etf",
    "cache_age_seconds": 0,
    "freshness": "unsupported",
    "market_status": "open",
    "reason": "etf_no_valuation_multiples",
    "symbol": "SPY"
  }
}
```

### Non-payer (TSLA)

`dividend_yield_pct` is an `{available: false, reason: "no_dividend_payer"}` object, not 0.

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:09Z",
    "cache_age_seconds": 0,
    "currency": "USD",
    "enterprise_value_usd": 1534691163705,
    "freshness": "intraday",
    "market_cap_usd": 1570205163705,
    "market_status": "open",
    "multiples": {
      "ev_ebit_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 91.34,
          "percentile_5y": 98,
          "position": "premium"
        },
        "value": 268.68
      },
      "ev_ebitda_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 61.31,
          "percentile_5y": 94,
          "position": "premium"
        },
        "value": 127.86
      },
      "ev_sales_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 10.68,
          "percentile_5y": 84,
          "position": "premium"
        },
        "value": 15.68
      },
      "pb": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 15.75,
          "percentile_5y": 70,
          "position": "above_median"
        },
        "value": 18.67
      },
      "pe_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 74,
          "median_5y": 69.34,
          "percentile_5y": 100,
          "position": "premium"
        },
        "value": 406.58
      },
      "peg_1y": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 0.22,
          "percentile_5y": 99,
          "position": "premium"
        },
        "value": 26.43
      },
      "ps_ttm": {
        "context": {
          "available": true,
          "coverage_pct": 100,
          "median_5y": 10.97,
          "percentile_5y": 84,
          "position": "premium"
        },
        "value": 16.04
      }
    },
    "returns_on_capital": {
      "flags": [],
      "roa_pct": 2.84,
      "roce_pct": 5.5,
      "roe_pct": 4.77,
      "roic_pct": 5.5
    },
    "symbol": "TSLA",
    "valuation_context": {
      "anchor": "pe_ttm",
      "coverage_pct": 74,
      "median_5y": 69.34,
      "percentile_5y": 100,
      "position": "premium",
      "rationale": "positive_earnings_period",
      "value": 406.58
    },
    "yields": {
      "buyback_yield_pct_ttm": 0,
      "dividend_yield_pct": {
        "available": false,
        "reason": "no_dividend_payer"
      },
      "earnings_yield_pct": 0.25,
      "fcf_yield_pct": 0.45,
      "total_payout_yield_pct_ttm": 0
    }
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/valuation?symbol=NVDA" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/valuation",
    params={"symbol": "NVDA"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/valuation?symbol=NVDA", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Check symbol coverage (/docs/api-reference/endpoints/discovery/coverage)

`GET https://api.noxstock.com/v2/coverage`

Per-symbol support map: the asset type plus a `supported` flag (with a `reason` when false) for every data family — snapshot, valuation, fundamentals, filings, insider, and the rest. One call tells you which endpoints apply to a symbol before you make any of them.

Access: all plans, including Free.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (AAPL)

```json
{
  "data": {
    "asset_type": "stock",
    "cache_age_seconds": 0,
    "support": {
      "calendar": {
        "supported": true
      },
      "dividends": {
        "supported": true
      },
      "earnings": {
        "supported": true
      },
      "filings": {
        "supported": true
      },
      "fundamentals": {
        "supported": true
      },
      "history": {
        "supported": true
      },
      "insider": {
        "supported": true
      },
      "price_action": {
        "supported": true
      },
      "profile": {
        "supported": true
      },
      "snapshot": {
        "supported": true
      },
      "technicals": {
        "supported": true
      },
      "valuation": {
        "supported": true
      }
    },
    "symbol": "AAPL"
  }
}
```

### ETF (SPY)

ETFs support market-data families; earnings, fundamentals, filings, and insider report `supported: false` with a reason.

```json
{
  "data": {
    "asset_type": "etf",
    "cache_age_seconds": 0,
    "support": {
      "calendar": {
        "supported": true
      },
      "dividends": {
        "supported": true
      },
      "earnings": {
        "reason": "etf_no_earnings_reports",
        "supported": false
      },
      "filings": {
        "reason": "not_applicable_for_etf",
        "supported": false
      },
      "fundamentals": {
        "reason": "etf_no_standalone_financial_statements",
        "supported": false
      },
      "history": {
        "supported": true
      },
      "insider": {
        "reason": "etf_no_insider_transactions",
        "supported": false
      },
      "price_action": {
        "supported": true
      },
      "profile": {
        "supported": true
      },
      "snapshot": {
        "supported": true
      },
      "technicals": {
        "supported": true
      },
      "valuation": {
        "reason": "etf_no_valuation_multiples",
        "supported": false
      }
    },
    "symbol": "SPY"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/coverage?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/coverage",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/coverage?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Search supported symbols (/docs/api-reference/endpoints/discovery/search)

`GET https://api.noxstock.com/v2/search`

Resolve a ticker fragment or company name to supported symbols. Returns ranked matches with symbol, name, asset type, and exchange. Call this before storing user-entered input — unknown symbols fail later calls with `SYMBOL_UNKNOWN`.

Access: all plans, including Free.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `query` | query | no | Free-text search query matched against ticker symbol and issuer name. Case-insensitive; whitespace and punctuation are normalized. |
| `q` | query | no | Alias for `query` (back-compat). |

## Response examples (captured from production)

### Name search

```json
{
  "data": {
    "cache_age_seconds": 0,
    "matches": [
      {
        "asset_type": "stock",
        "exchange": "NASDAQ",
        "name": "Apple Inc.",
        "symbol": "AAPL"
      },
      {
        "asset_type": "stock",
        "exchange": "NYSE",
        "name": "Apple Hospitality REIT, Inc.",
        "symbol": "APLE"
      },
      {
        "asset_type": "stock",
        "exchange": "NYSE",
        "name": "MAUI LAND & PINEAPPLE CO INC",
        "symbol": "MLP"
      }
    ],
    "query": "apple"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/search?query=apple" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/search",
    params={"query": "apple"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/search?query=apple", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get symbol calendar (/docs/api-reference/endpoints/events/calendar)

`GET https://api.noxstock.com/v2/calendar`

Upcoming per-symbol events — estimated next earnings and dividend dates — derived from that symbol's own statement and dividend history. Not a market-wide calendar; an empty `upcoming` array is a normal answer.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (AAPL)

```json
{
  "data": {
    "as_of": "2026-06-05T09:51:01Z",
    "cache_age_seconds": 16091,
    "freshness": "end_of_day",
    "market_status": "open",
    "symbol": "AAPL",
    "upcoming": [
      {
        "date": "2026-07-31",
        "details": "Estimated from recent earnings cadence",
        "estimated": true,
        "type": "earnings"
      },
      {
        "date": "2026-07-31",
        "details": "Expected SEC filing based on recent statement filing cadence",
        "estimated": true,
        "type": "filing_expected"
      },
      {
        "date": "2026-08-10",
        "details": "$0.27 quarterly cadence",
        "estimated": true,
        "type": "ex_dividend"
      }
    ]
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/calendar?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/calendar",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/calendar?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get dividends (/docs/api-reference/endpoints/financials/dividends)

`GET https://api.noxstock.com/v2/dividends`

Current yield, annual rate, frequency, next estimated ex-date, growth streaks, and a dividend-health grade. Non-payers return `status: "non_payer"` with `{available: false, reason}` objects — never a fake 0% yield.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Payer (AAPL)

```json
{
  "data": {
    "as_of": "2026-06-05T09:50:57Z",
    "cache_age_seconds": 16093,
    "currency": "USD",
    "current": {
      "annual_rate": 1.08,
      "annual_rate_forward_estimated": 1.08,
      "frequency": "quarterly",
      "last_ex_date": "2026-05-11",
      "last_payment_amount": 0.27,
      "next_ex_date_estimated": "2026-08-10",
      "next_payment_amount_estimated": 0.27,
      "yield_pct": 0.35
    },
    "dividend_health": {
      "grade_components": {
        "ebitda_coverage": 10.31,
        "fcf_payout_ratio_pct": 12.04,
        "net_debt_to_ebitda": 0.1,
        "ocf_coverage": 9.02,
        "payout_ratio_pct": 12.69
      },
      "payout_safety": {
        "available": true,
        "grade": "A"
      },
      "track_record": {
        "consecutive_increase_years": 5,
        "cuts_in_5y_window": 0,
        "never_cut_in_5y_window": true
      }
    },
    "freshness": "end_of_day",
    "growth": {
      "consecutive_years_increased_within_5y_window": 5,
      "last_increase_date": "2026-05-11"
    },
    "history_summary": {
      "ex_date_first": "2021-08-06",
      "total_payments": 20
    },
    "market_status": "open",
    "status": "payer",
    "symbol": "AAPL"
  }
}
```

### Non-payer (TSLA)

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:10Z",
    "cache_age_seconds": 0,
    "currency": "USD",
    "current": {
      "annual_rate": 0,
      "frequency": "none",
      "yield_pct": {
        "available": false,
        "reason": "no_dividend_payer"
      }
    },
    "dividend_health": {
      "reason": "no_dividend_payments",
      "supported": false
    },
    "freshness": "intraday",
    "growth": {
      "reason": "no_dividend_history",
      "supported": false
    },
    "history_summary": {
      "ex_date_first": {
        "available": false,
        "reason": "no_dividend_history"
      },
      "total_payments": 0
    },
    "market_status": "open",
    "status": "non_payer",
    "symbol": "TSLA"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/dividends?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/dividends",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/dividends?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get earnings context (/docs/api-reference/endpoints/financials/earnings)

`GET https://api.noxstock.com/v2/earnings`

The last report (EPS and revenue with year-over-year change and a trend reading), an estimated next report date, and a per-quarter history. Stocks only — ETFs return `freshness: "unsupported"` because ETFs do not report earnings.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (AAPL)

History trimmed to 3 quarters for display.

```json
{
  "data": {
    "as_of": "2026-06-05T09:50:56Z",
    "cache_age_seconds": 16094,
    "currency": "USD",
    "freshness": "end_of_day",
    "history": [
      {
        "eps_actual": 2.84,
        "eps_yoy_pct": 18.33,
        "filing_date": "2026-01-30",
        "fiscal_period": "Q1",
        "fiscal_year": 2026,
        "period_end": "2025-12-27",
        "revenue_actual": 143756000000,
        "revenue_yoy_pct": 15.65
      },
      {
        "eps_actual": 1.84,
        "eps_yoy_pct": 89.69,
        "filing_date": "2025-10-31",
        "fiscal_period": "Q4",
        "fiscal_year": 2025,
        "period_end": "2025-09-27",
        "revenue_actual": 102466000000,
        "revenue_yoy_pct": 7.94
      },
      {
        "eps_actual": 1.57,
        "eps_yoy_pct": 12.14,
        "filing_date": "2025-08-01",
        "fiscal_period": "Q3",
        "fiscal_year": 2025,
        "period_end": "2025-06-28",
        "revenue_actual": 94036000000,
        "revenue_yoy_pct": 9.63
      }
    ],
    "last": {
      "eps_actual": 2.01,
      "eps_yoy_pct": 21.82,
      "filing_date": "2026-05-01",
      "fiscal_period": "Q2",
      "fiscal_year": 2026,
      "period_end": "2026-03-28",
      "revenue_actual": 111184000000,
      "revenue_yoy_pct": 16.6,
      "vs_trend": {
        "eps_baseline_4q_avg": 1.98,
        "eps_vs_trailing_4q_avg_pct": 1.77,
        "revenue_baseline_4q_avg": 108904250000,
        "revenue_vs_trailing_4q_avg_pct": 2.09
      }
    },
    "market_status": "open",
    "next_estimated_date": "2026-07-31",
    "symbol": "AAPL"
  }
}
```

### ETF (SPY) — unsupported

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:10Z",
    "asset_type": "etf",
    "cache_age_seconds": 0,
    "freshness": "unsupported",
    "market_status": "open",
    "reason": "etf_no_earnings_reports",
    "symbol": "SPY"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/earnings?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/earnings",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/earnings?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get fundamentals (/docs/api-reference/endpoints/financials/fundamentals)

`GET https://api.noxstock.com/v2/fundamentals`

Curated statement rows — income statement, balance sheet, cash flow — for up to eight quarterly or annual periods, plus a TTM block with margins and returns on capital. Decision-shaped rows, not raw filings.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |
| `period` | query | no | Reporting cadence. Allowed values: quarter (default, last 8 quarters) or annual (last 5 fiscal years). |

## Response examples (captured from production)

### Quarterly (AAPL)

Statement arrays trimmed to 2 periods for display; live responses return up to 8.

```json
{
  "data": {
    "as_of": "2026-06-05T09:50:54Z",
    "balance_sheet": [
      {
        "cash_and_equivalents": 45572000000,
        "common_shares_outstanding": 14681140000,
        "current_assets": 144114000000,
        "current_liabilities": 134641000000,
        "fiscal_period": "Q2",
        "fiscal_year": 2026,
        "intangibles": 21334000000,
        "inventory": 6747000000,
        "long_term_debt": 74404000000,
        "long_term_investments": 78088000000,
        "net_debt": 16204000000,
        "period_end": "2026-03-28",
        "ppe_net": 50116000000,
        "ratios": {
          "current_ratio": 1.07,
          "debt_to_assets": 0.23,
          "debt_to_equity": 0.8,
          "interest_coverage": {
            "available": false,
            "reason": "zero_interest_expense"
          },
          "net_debt_to_ebitda": 0.1
        },
        "receivables": 53511000000,
        "retained_earnings": 12359000000,
        "short_term_investments": 22935000000,
        "tangible_book_value": 85157000000,
        "total_assets": 371082000000,
        "total_debt": 84711000000,
        "total_equity": 106491000000,
        "total_liabilities": 264591000000
      },
      {
        "cash_and_equivalents": 45317000000,
        "common_shares_outstanding": 14776353000,
        "current_assets": 158104000000,
        "current_liabilities": 162367000000,
        "fiscal_period": "Q1",
        "fiscal_year": 2026,
        "intangibles": 0,
        "inventory": 5875000000,
        "long_term_debt": 76685000000,
        "long_term_investments": 77888000000,
        "net_debt": 23602000000,
        "period_end": "2025-12-27",
        "ppe_net": 50159000000,
        "ratios": {
          "current_ratio": 0.97,
          "debt_to_assets": 0.24,
          "debt_to_equity": 1.03,
          "interest_coverage": {
            "available": false,
            "reason": "zero_interest_expense"
          },
          "net_debt_to_ebitda": 0.15
        },
        "receivables": 70320000000,
        "retained_earnings": -2177000000,
        "short_term_investments": 21590000000,
        "tangible_book_value": 88190000000,
        "total_assets": 379297000000,
        "total_debt": 90509000000,
        "total_equity": 88190000000,
        "total_liabilities": 291107000000
      }
    ],
    "cache_age_seconds": 16096,
    "cash_flow": [
      {
        "acquisitions": 0,
        "buybacks": -12288000000,
        "capex": -1971000000,
        "dividends_paid": -3822000000,
        "fcf_margin_pct": 24.04,
        "fcf_yoy_pct": 28.02,
        "financing_cash_flow": -22279000000,
        "fiscal_period": "Q2",
        "fiscal_year": 2026,
        "free_cash_flow": 26731000000,
        "investing_cash_flow": -6168000000,
        "ocf_yoy_pct": 19.83,
        "operating_cash_flow": 28702000000,
        "period_end": "2026-03-28",
        "stock_based_comp": 3528000000,
        "working_capital_change": 13736000000
      },
      {
        "acquisitions": 0,
        "buybacks": -24701000000,
        "capex": -2373000000,
        "dividends_paid": -3921000000,
        "fcf_margin_pct": 35.86,
        "fcf_yoy_pct": 90.97,
        "financing_cash_flow": -39656000000,
        "fiscal_period": "Q1",
        "fiscal_year": 2026,
        "free_cash_flow": 51552000000,
        "investing_cash_flow": -4886000000,
        "ocf_yoy_pct": 80.14,
        "operating_cash_flow": 53925000000,
        "period_end": "2025-12-27",
        "stock_based_comp": 3594000000,
        "working_capital_change": 13411000000
      }
    ],
    "currency": "USD",
    "freshness": "end_of_day",
    "income_statement": [
      {
        "cost_of_revenue": 56403000000,
        "depreciation_amortization": 3439000000,
        "ebitda": 39272000000,
        "eps_basic": 2.02,
        "eps_diluted": 2.01,
        "fiscal_period": "Q2",
        "fiscal_year": 2026,
        "gross_profit": 54781000000,
        "growth": {
          "eps_yoy_pct": 21.82,
          "net_income_yoy_pct": 19.36,
          "revenue_qoq_pct": -22.66,
          "revenue_yoy_pct": 16.6,
          "rnd_yoy_pct": 33.56
        },
        "income_tax": 6255000000,
        "interest_coverage": {
          "available": false,
          "reason": "zero_interest_expense"
        },
        "interest_expense": 0,
        "investment": {
          "capex_intensity_3y_avg_pct": 2.5,
          "capex_intensity_pct": 1.77,
          "rnd_intensity_pct": 10.27
        },
        "margins": {
          "ebitda_margin_pct": 35.32,
          "gross_margin_pct": 49.27,
          "net_margin_pct": 26.6,
          "operating_margin_pct": 32.28
        },
        "net_income": 29578000000,
        "operating_expense": 18896000000,
        "operating_income": 35885000000,
        "period_end": "2026-03-28",
        "pretax_income": 35833000000,
        "quality": {
          "piotroski_f_score": 8,
          "piotroski_status": {
            "available": true
          }
        },
        "revenue": 111184000000,
        "rnd_expense": 11419000000,
        "sga_expense": 7477000000,
        "shares_basic": 14673278000,
        "shares_diluted": 14725873000
      },
      {
        "cost_of_revenue": 74525000000,
        "depreciation_amortization": 3214000000,
        "ebitda": 54216000000,
        "eps_basic": 2.85,
        "eps_diluted": 2.84,
        "fiscal_period": "Q1",
        "fiscal_year": 2026,
        "gross_profit": 69231000000,
        "growth": {
          "eps_yoy_pct": 18.33,
          "net_income_yoy_pct": 15.87,
          "revenue_qoq_pct": 40.3,
          "revenue_yoy_pct": 15.65,
          "rnd_yoy_pct": 31.68
        },
        "income_tax": 8905000000,
        "interest_coverage": {
          "available": false,
          "reason": "zero_interest_expense"
        },
        "interest_expense": 0,
        "investment": {
          "capex_intensity_3y_avg_pct": 2.01,
          "capex_intensity_pct": 1.65,
          "rnd_intensity_pct": 7.57
        },
        "margins": {
          "ebitda_margin_pct": 37.71,
          "gross_margin_pct": 48.16,
          "net_margin_pct": 29.28,
          "operating_margin_pct": 35.37
        },
        "net_income": 42097000000,
        "operating_expense": 18379000000,
        "operating_income": 50852000000,
        "period_end": "2025-12-27",
        "pretax_income": 51002000000,
        "quality": {
          "piotroski_f_score": 9,
          "piotroski_status": {
            "available": true
          }
        },
        "revenue": 143756000000,
        "rnd_expense": 10887000000,
        "sga_expense": 7492000000,
        "shares_basic": 14748158000,
        "shares_diluted": 14810356000
      }
    ],
    "market_status": "open",
    "period": "quarter",
    "symbol": "AAPL",
    "ttm": {
      "eps_diluted_ttm": 8.26,
      "flags": [
        "zero_interest_expense"
      ],
      "net_income_ttm_usd": 122575000000,
      "net_profit_margin_pct": 27.15,
      "revenue_ttm_usd": 451442000000,
      "roa_pct": 34.02,
      "roce_pct": 83.04,
      "roe_pct": 146.69,
      "roic_pct": 83.04
    }
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/fundamentals?symbol=AAPL&period=quarter" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/fundamentals",
    params={"symbol": "AAPL", "period": "quarter"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/fundamentals?symbol=AAPL&period=quarter", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get selected history series (/docs/api-reference/endpoints/market-context/history)

`GET https://api.noxstock.com/v2/history`

Selected time series in columnar `{columns, rows}` form: price, volume, RSI, financial ratios, or dividends, at daily through annual cadence. Daily price history covers up to 5 years. Request only the series you need — payloads grow fast. `period` is accepted as a legacy alias for `range`.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |
| `series` | query | no | Comma-separated list of history series, max 3. Allowed values: close, volume, rsi_14, roic_pct, fcf_margin_pct, gross_margin_pct, dividend. daily/weekly support close, volume, rsi_14; quarterly/annual support roic_pct, fcf_margin_pct, gross_margin_pct; per-payment supports dividend. The dividend series requires cadence=per-payment explicitly. |
| `range` | query | no | Historical lookback window. Allowed values: 1m, 1mo, 3m, 3mo, 6m, 6mo, 1y, 2y, 5y, 10y, 30y, ytd, max. Long `mo` forms normalize to short month forms; `max` is capped at 30y. |
| `period` | query | no | Legacy alias for `range` (back-compat). |
| `cadence` | query | no | Row cadence. Allowed values: daily, weekly, quarterly, annual, per-payment. Required as per-payment when series=dividend. |

## Response examples (captured from production)

### Daily closes, 1 month (AAPL)

Rows trimmed to 6 for display; this request returns ~22 rows live.

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:11Z",
    "cache_age_seconds": 0,
    "cadence": "daily",
    "columns": [
      "date",
      "close"
    ],
    "freshness": "intraday",
    "market_status": "open",
    "period": "1m",
    "rows": [
      [
        "2026-05-05",
        283.9180829493
      ],
      [
        "2026-05-06",
        287.2450138249
      ],
      [
        "2026-05-07",
        287.175078341
      ],
      [
        "2026-05-08",
        293.0496589862
      ],
      [
        "2026-05-11",
        292.68
      ],
      [
        "2026-05-12",
        294.8
      ]
    ],
    "symbol": "AAPL"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/history?symbol=AAPL&series=close&range=1m" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/history",
    params={"symbol": "AAPL", "series": "close", "range": "1m"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/history?symbol=AAPL&series=close&range=1m", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get price action (/docs/api-reference/endpoints/market-context/price-action)

`GET https://api.noxstock.com/v2/price-action`

How the price is behaving: volume vs 30-day and sector averages, 30/90-day extremes, gap and streak context, biggest single-day moves, and max drawdowns over 90 days, 1 year, and 5 years.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (AAPL)

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:11Z",
    "cache_age_seconds": 0,
    "drawdowns": {
      "max_1y": {
        "pct": -13.8,
        "peak_date": "2025-12-02",
        "trough_date": "2026-01-20"
      },
      "max_5y": {
        "pct": -33.36,
        "peak_date": "2024-12-26",
        "trough_date": "2025-04-08"
      },
      "max_90d": {
        "pct": -11.24,
        "peak_date": "2026-02-06",
        "trough_date": "2026-03-30"
      }
    },
    "freshness": "intraday",
    "gaps": {
      "latest_open_vs_prior_close_pct": 0.96,
      "unfilled_gaps_30d": 1
    },
    "market_status": "open",
    "recent_extremes": {
      "high_30d": {
        "date": "2026-06-03",
        "value": 316.94
      },
      "high_90d": {
        "date": "2026-06-03",
        "value": 316.94
      },
      "low_30d": {
        "date": "2026-04-27",
        "value": 264.83
      },
      "low_90d": {
        "date": "2026-03-30",
        "value": 245.28
      }
    },
    "streaks": {
      "biggest_down_day_1y_pct": -5,
      "biggest_down_day_30d_pct": -1.84,
      "biggest_up_day_1y_pct": 5.09,
      "biggest_up_day_30d_pct": 3.24,
      "consecutive_days": 0,
      "direction": "none"
    },
    "symbol": "AAPL",
    "trend_context": {
      "consecutive_higher_highs": 0,
      "consecutive_lower_lows": 0,
      "pct_days_above_sma50_90d": 53
    },
    "volume": {
      "avg_30d": 48146449,
      "latest": 44869134,
      "ratio_to_avg": 0.93,
      "ratio_to_sector_avg": 3.75,
      "ratio_to_sector_status": {
        "supported": true
      }
    }
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/price-action?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/price-action",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/price-action?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get technical indicators (/docs/api-reference/endpoints/market-context/technicals)

`GET https://api.noxstock.com/v2/technicals`

Daily and weekly RSI with zone readings, stochastic, MACD, SMA/EMA relationships with golden-cross state, ADX trend strength, OBV, Bollinger bands, ATR, realized volatility, beta, and relative strength vs SPY and sector — one call, computed server-side.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |

## Response examples (captured from production)

### Stock (AAPL)

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:11Z",
    "cache_age_seconds": 0,
    "freshness": "intraday",
    "market_status": "open",
    "momentum": {
      "macd": {
        "above_signal": false,
        "histogram": -0.48,
        "signal_line": 9.68,
        "value": 9.2
      },
      "rsi_14": 66.61,
      "rsi_14_weekly": 71.17,
      "rsi_14_weekly_zone": "overbought",
      "rsi_zone": "neutral",
      "stochastic_14_3_3": {
        "d": 80.08,
        "k": 80.87,
        "zone": "overbought"
      }
    },
    "moving_averages": {
      "distance_from_52w_high_pct": -1.8,
      "ema_20": 302.13,
      "golden_cross_active": true,
      "sma_200": 264.38,
      "sma_50": 279.99,
      "vs_sma_200_pct": 17.72,
      "vs_sma_50_pct": 11.16
    },
    "relative_strength": {
      "vs_sector_1y_pct": -10.01,
      "vs_sector_status": {
        "supported": true
      },
      "vs_spy_1m_pct": 5.02,
      "vs_spy_1y_pct": 25.56,
      "vs_spy_3m_pct": 8.09
    },
    "symbol": "AAPL",
    "trend_strength": {
      "adx_14": 45.73,
      "adx_14_weekly": 20.25,
      "obv": 3635324275,
      "obv_trend_30d": "up",
      "trending": true,
      "trending_weekly": false
    },
    "volatility": {
      "atr_14": 5.92,
      "beta_1y": 0.96,
      "bollinger_20": {
        "lower": 287.78,
        "middle": 303.23,
        "percent_b": 0.76,
        "upper": 318.68
      },
      "realized_vol_30d_annualized_pct": 19.36
    }
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/technicals?symbol=AAPL" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/technicals",
    params={"symbol": "AAPL"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/technicals?symbol=AAPL", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get filing section text (/docs/api-reference/endpoints/sec-filings/filing-section)

`GET https://api.noxstock.com/v2/filings/{accession}/section/{name}`

Full text of one section of a filing: `risk_factors`, `mda`, `business`, and peers for 10-K/10-Q, or `press_release` for 8-K. `char_count` arrives before you commit to reading — sections run from a few KB to several hundred KB, so fetch only what you will actually read.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `accession` | path | yes | SEC accession number in dashed form (e.g. 0000320193-25-000001). |
| `name` | path | yes | Filing section name. Allowed values: business, risk_factors, mda, quantitative_qualitative_disclosures, controls_and_procedures, press_release. |
| `symbol` | query | no | Optional cross-check. When supplied, the filing's resolved filer must match this symbol or the request fails with `PARAM_INVALID`. |

## Response examples (captured from production)

### Risk factors (10-K)

`text` truncated for display; live responses return the full section.

```json
{
  "data": {
    "accession": "0000320193-25-000079",
    "as_of": "2026-06-05T14:19:24Z",
    "available": true,
    "cache_age_seconds": 12,
    "char_count": 68069,
    "form": "10-K",
    "freshness": "intraday",
    "market_status": "open",
    "section": "risk_factors",
    "symbol": "AAPL",
    "symbol_status": {
      "resolved": true
    },
    "text": "Item 1A.    Risk Factors\nThe following summarizes factors that could have a material adverse effect on the Company’s business, reputation, results of operations, financial condition and stock price. The Company may not be able to accurately predict, control or mitigate these risks. Statements in this section are based on the Company’s beliefs and opinions regarding matters that could materially adversely affect the C … [truncated for docs]"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/filings/0000320193-25-000079/section/risk_factors" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/filings/0000320193-25-000079/section/risk_factors",
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/filings/0000320193-25-000079/section/risk_factors", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get filing metadata (/docs/api-reference/endpoints/sec-filings/filing)

`GET https://api.noxstock.com/v2/filings/{accession}`

Metadata for one filing by accession number. The shape follows the form type: 10-K/10-Q responses include a `sections` index (what you can fetch as text), 8-K responses include `items` and press-release availability, and Form 4 responses carry the filing facts only. A well-formed accession that matches no filing returns a 200 with `symbol_status: {resolved: false}`.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `accession` | path | yes | SEC accession number in dashed form (e.g. 0000320193-25-000001). |
| `symbol` | query | no | Optional cross-check. When supplied, the filing's resolved filer must match this symbol or the request fails with `PARAM_INVALID`. |

## Response examples (captured from production)

### 10-K

```json
{
  "data": {
    "accession": "0000320193-25-000079",
    "as_of": "2026-06-05T14:19:12Z",
    "cache_age_seconds": 0,
    "filing_date": "2025-10-31",
    "form": "10-K",
    "freshness": "intraday",
    "market_status": "open",
    "period_of_report": "2025-09-27",
    "sections": [
      {
        "char_count": 16004,
        "name": "business"
      },
      {
        "char_count": 68069,
        "name": "risk_factors"
      },
      {
        "char_count": 21009,
        "name": "mda"
      }
    ],
    "symbol": "AAPL",
    "symbol_status": {
      "resolved": true
    },
    "url": "https://www.sec.gov/Archives/edgar/data/320193/0000320193-25-000079-index.html"
  }
}
```

### 8-K

```json
{
  "data": {
    "accession": "0000320193-26-000011",
    "as_of": "2026-06-05T14:19:24Z",
    "cache_age_seconds": 0,
    "filing_date": "2026-04-30",
    "form": "8-K",
    "freshness": "intraday",
    "items": [
      {
        "code": "2.02",
        "text": "Results of Operations and Financial Condition"
      },
      {
        "code": "9.01",
        "text": "Financial Statements and Exhibits"
      }
    ],
    "market_status": "open",
    "period_of_report": "2026-04-30",
    "press_release": {
      "available": true,
      "char_count": 27021
    },
    "symbol": "AAPL",
    "symbol_status": {
      "resolved": true
    },
    "url": "https://www.sec.gov/Archives/edgar/data/320193/0000320193-26-000011-index.html"
  }
}
```

### Form 4

```json
{
  "data": {
    "accession": "0001140361-26-023363",
    "as_of": "2026-06-05T14:19:29Z",
    "cache_age_seconds": 0,
    "filing_date": "2026-05-29",
    "form": "4",
    "freshness": "intraday",
    "market_status": "open",
    "period_of_report": "2026-05-27",
    "symbol": "AAPL",
    "symbol_status": {
      "resolved": true
    },
    "url": "https://www.sec.gov/Archives/edgar/data/320193/0001140361-26-023363-index.html"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/filings/0000320193-25-000079" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/filings/0000320193-25-000079",
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/filings/0000320193-25-000079", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# List SEC filings (/docs/api-reference/endpoints/sec-filings/filings-list)

`GET https://api.noxstock.com/v2/filings`

Recent SEC filings for a stock, newest first, filtered by form type (default 10-K, 10-Q, 8-K). Each row carries the `accession` you pass to the filing metadata and section endpoints. First calls for a company can be slow while EDGAR data is cold; repeat calls are cached.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |
| `form` | query | no | Comma-separated SEC form-type filter. Allowed values: 10-K, 10-Q, 8-K, 4. Defaults to 10-K,10-Q,8-K when omitted. |
| `limit` | query | no | Maximum number of rows to return. Bounded by the endpoint-specific minimum / maximum constraints documented in the parameter schema. |

## Response examples (captured from production)

### Recent filings (AAPL)

Trimmed to 3 rows for display.

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:12Z",
    "cache_age_seconds": 0,
    "filings": [
      {
        "accession": "0000320193-26-000013",
        "filing_date": "2026-05-01",
        "form": "10-Q",
        "items": [],
        "items_text": [],
        "period_of_report": "2026-03-28",
        "sections": [],
        "size_bytes": 5809851,
        "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000013/aapl-20260328.htm"
      },
      {
        "accession": "0000320193-26-000011",
        "filing_date": "2026-04-30",
        "form": "8-K",
        "items": [
          "2.02",
          "9.01"
        ],
        "items_text": [],
        "period_of_report": "2026-04-30",
        "sections": [],
        "size_bytes": 412047,
        "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000011/aapl-20260430.htm"
      },
      {
        "accession": "0001140361-26-015711",
        "filing_date": "2026-04-20",
        "form": "8-K",
        "items": [
          "5.02"
        ],
        "items_text": [],
        "period_of_report": "2026-04-17",
        "sections": [],
        "size_bytes": 239761,
        "url": "https://www.sec.gov/Archives/edgar/data/320193/000114036126015711/ef20071035_8k.htm"
      }
    ],
    "freshness": "intraday",
    "market_status": "open",
    "symbol": "AAPL"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/filings?symbol=AAPL&form=10-K,10-Q&limit=5" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/filings",
    params={"symbol": "AAPL", "form": "10-K,10-Q", "limit": "5"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/filings?symbol=AAPL&form=10-K,10-Q&limit=5", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```

# Get insider activity (/docs/api-reference/endpoints/sec-filings/insider)

`GET https://api.noxstock.com/v2/insider`

Trailing-90-day Form 4 rollup: buy/sell counts and net value for open-market activity, all-kinds totals, the 10b5-1 planned-sale ratio, and officer/director split — plus the most recent transactions with codes, prices, and remaining stakes. Stocks only.

Access: Starter and Builder plans.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `symbol` | query | yes | Ticker symbol. Case-insensitive; share-class dots are normalized to dashes (BRK.B == BRK-B). Returns SYMBOL_UNKNOWN when the symbol is outside the supported universe. |
| `limit` | query | no | Maximum number of rows to return. Bounded by the endpoint-specific minimum / maximum constraints documented in the parameter schema. |

## Response examples (captured from production)

### Stock (AAPL)

Recent transactions trimmed to 3 for display.

```json
{
  "data": {
    "as_of": "2026-06-05T06:45:45Z",
    "cache_age_seconds": 27207,
    "freshness": "end_of_day",
    "market_status": "open",
    "recent_transactions": [
      {
        "accession": "0001140361-26-023363",
        "filing_date": "2026-05-29",
        "insider_name": "Arthur D Levinson",
        "insider_role": "Director",
        "price_per_share": 311.02,
        "shares": 50000,
        "shares_remaining": 3764576,
        "ten_b5_1": false,
        "transaction_code": "S",
        "transaction_date": "2026-05-27",
        "transaction_kind": "open_market_sale",
        "value_usd": 15551000
      },
      {
        "accession": "0001140361-26-023363",
        "filing_date": "2026-05-29",
        "insider_name": "Arthur D Levinson",
        "insider_role": "Director",
        "price_per_share": {
          "available": false,
          "reason": "gift_no_market_price"
        },
        "shares": 65000,
        "shares_remaining": 3764576,
        "ten_b5_1": false,
        "transaction_code": "G",
        "transaction_date": "2026-05-27",
        "transaction_kind": "gift",
        "value_usd": {
          "available": false,
          "reason": "gift_no_market_price"
        }
      },
      {
        "accession": "0001140361-26-020871",
        "filing_date": "2026-05-12",
        "insider_name": "Ben Borders",
        "insider_role": "Principal Accounting Officer",
        "price_per_share": 290,
        "shares": 1274,
        "shares_remaining": 38713,
        "ten_b5_1": false,
        "transaction_code": "S",
        "transaction_date": "2026-05-08",
        "transaction_kind": "open_market_sale",
        "value_usd": 369460
      }
    ],
    "summary_90d": {
      "all_activity": {
        "net_shares_all_kinds": 25895,
        "transactions": 43,
        "transactions_by_kind": {
          "derivative_exercise": 22,
          "gift": 2,
          "open_market_sale": 13,
          "tax_withholding": 6
        }
      },
      "director_share_pct": 12,
      "market_activity": {
        "buy_count": 0,
        "net_direction": "selling",
        "net_shares_market_only": -397759,
        "net_value_usd": -111705105.08,
        "sell_count": 13
      },
      "notices": [
        "recent_transactions_limited_to_10"
      ],
      "officer_share_pct": 42,
      "ten_b5_1_plan_ratio_pct": 0,
      "unique_insiders": 7
    },
    "symbol": "AAPL"
  }
}
```

### ETF (SPY) — unsupported

```json
{
  "data": {
    "as_of": "2026-06-05T14:19:12Z",
    "asset_type": "etf",
    "cache_age_seconds": 0,
    "freshness": "unsupported",
    "market_status": "open",
    "reason": "etf_no_insider_transactions",
    "symbol": "SPY"
  }
}
```

## Errors

All errors share the envelope `{ "error": { "code", "message", "retryable" } }`.

- `400` Invalid symbol or query parameters.
- `401` Missing, invalid, or revoked `X-API-Key`.
- `403` The key's plan does not include this endpoint.
- `404` The symbol is outside the supported universe. Use `/v2/search` to resolve it.
- `429` Per-minute rate limit or plan quota exceeded. Honor `Retry-After`.
- `503` The data source or key verification is temporarily unavailable. Retryable.

## Code samples

### curl

```bash
curl "https://api.noxstock.com/v2/insider?symbol=AAPL&limit=10" \
  -H "X-API-Key: $NOXSTOCK_API_KEY"
```

### Python

```python
import os
import httpx

response = httpx.get(
    "https://api.noxstock.com/v2/insider",
    params={"symbol": "AAPL", "limit": "10"},
    headers={"X-API-Key": os.environ["NOXSTOCK_API_KEY"]},
)
body = response.json()
if "error" in body:
    error = body["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")
data = body["data"]
```

### TypeScript

```typescript
const res = await fetch("https://api.noxstock.com/v2/insider?symbol=AAPL&limit=10", {
  headers: { "X-API-Key": process.env.NOXSTOCK_API_KEY! },
});
const body = await res.json();
if ("error" in body) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const data = body.data;
```